[Bps-public-commit] rt-extension-rest2 branch, rt-extension-rest2-docs, created. 1.01-1-g31a3204

Craig Kaiser craig at bestpractical.com
Mon Feb 12 11:48:00 EST 2018


The branch, rt-extension-rest2-docs has been created
        at  31a3204957be10dfd9f5e155d395c7a1f7a3927b (commit)

- Log -----------------------------------------------------------------
commit 31a3204957be10dfd9f5e155d395c7a1f7a3927b
Author: Craig Kaiser <craig at bestpractical.com>
Date:   Mon Feb 12 08:40:09 2018 -0500

    Update REST2 docs with examples and clearer notation
    
    Add examples of REST2.0 query with GET and POST methods, as well removing
    confusing lines about GET method. Most of the endpoints have a line of
    documentation about using GET 'REST/2.0/endpoint?query=<JSON>',
    this is highly confusing. The GET method cannot send JSON as an
    arguement and the only endpoint that accepts '?query=' is Tickets. Removing
    this information and adding examples of querying of the GET method will
    alleviate in the confusion.

diff --git a/lib/RT/Extension/REST2.pm b/lib/RT/Extension/REST2.pm
index b7e2a7b..ea77d7f 100644
--- a/lib/RT/Extension/REST2.pm
+++ b/lib/RT/Extension/REST2.pm
@@ -138,6 +138,81 @@ include this hyperlink in its response to your request. This allows you
 to dynamically adapt your client's behavior to its presence or absence,
 just like the web version of RT does.
 
+
+=head3 GET Examples
+
+If we need to get information on an endpoint quickly, we can use the GET method.
+
+    curl -X GET -u 'root:password' 'REST/2.0/tickets?query=id=1'
+
+    curl -X GET -u 'root:password' 'REST/2.0/user/root/history'
+
+If successful we can expect a list of transactions from the user like so:
+
+    "per_page" : 20,
+    "page" : 1,
+    "count" : 1,
+    "total" : 1,
+    "items" : [
+        {
+            "id" : "11",
+            "type" : "transaction",
+            "_url" : "REST/2.0/transaction/11"
+        },
+    ]}
+
+    curl -X GET -u 'root:password' 'REST/2.0/group/2/'
+
+Here we can get the information on a group such as:
+     "Members"
+        {
+            "_url" : "http://localhost:8080/REST/2.0/user/RT_System",
+            "type" : "user",
+            "id" : "RT_System"
+        }
+        "LastUpdatedBy" : "0",
+        "Creator" : "0",
+        "Domain" : "ACLEquivalence",
+        "Name" : "UserEquiv",
+        "_hyperlinks",
+        "Description"
+        "id" : 2,
+        "LastUpdated" : "2017-10-24T19:15:35Z",
+        "Created" : "2017-10-24T19:15:35Z",
+        "Instance" : {
+            "type" : "user",
+            "id" : "RT_System",
+            "_url" : "REST/2.0/user/RT_System"
+        },
+        "CustomFields" : {}
+
+=head3 POST Examples
+
+All the REST2.0 endpoints offer a POST method for creating and querying, some
+examples of this can be viewed below.
+
+Creating a new Asset:
+
+    curl -X POST -H "Content-Type: application/json"
+        -d '{"subject": "Creating a asset from rest2 api"}'
+        -u 'root:password'
+        '/REST/2.0/asset?Catalog=1'
+
+Result:
+
+{"_url":"/REST/2.0/asset/10","id":"10","type":"asset"}
+
+Creating a new User:
+
+    curl -X POST -H "Content-Type: application/json"
+        -d '{"Name": "TestUser", "Nickname": "Tester"}'
+        -u 'root:password'
+        '/REST/2.0/user'
+
+Name is a mandatory field:
+
+{"_url":"http://localhost:8080/REST/2.0/user/TestUser","id":"TestUser","type":"user"}
+
 =head3 Creating Tickets
 
 Let's use the C<_url> from the C<create> hyperlink with type C<ticket>.
@@ -162,6 +237,13 @@ If successful, that will provide output like so:
         "id"   : "20"
     }
 
+    curl -X POST -H "Content-Type: application/json"
+        -d '{"Subject": "Ticket Create using REST", "Priority": 42}'
+        -u 'root:password'
+        '/REST/2.0/ticket?Queue=1'
+
+    {"_url":"/REST/2.0/ticket/68","type":"ticket","id":"1"}
+
 (REST2 also produces the status code of C<201 Created> with a C<Location>
 header of the new ticket, which you may choose to use instead of the
 JSON response)
@@ -194,6 +276,10 @@ like a ticket creation.
          -H 'Authorization: token XX_TOKEN_XX'
             'XX_TICKET_URL_XX'
 
+    curl -X PUT -H "Content-Type: application/json" -d
+        '{"Subject": "Ticket update using REST", "Priority": 42}'
+        -u 'root:password' 'REST/2.0/ticket/8'
+
 You'll get an error response like C<{"message":"Precondition Failed"}>
 and a status code of 412. If you examine the ticket, you'll also see
 that its Subject was not changed. This is because the C<If-Match> header
@@ -282,7 +368,6 @@ controls available in response bodies rather than hardcoding URLs.
 
 =head3 Transactions
 
-    GET /transactions?query=<JSON>
     POST /transactions
         search for transactions using L</JSON searches> syntax
 
@@ -300,7 +385,6 @@ controls available in response bodies rather than hardcoding URLs.
 
 =head3 Attachments and Messages
 
-    GET /attachments?query=<JSON>
     POST /attachments
         search for attachments using L</JSON searches> syntax
 
@@ -315,7 +399,6 @@ controls available in response bodies rather than hardcoding URLs.
     GET /queues/all
         retrieve list of all queues you can see
 
-    GET /queues?query=<JSON>
     POST /queues
         search for queues using L</JSON searches> syntax
 
@@ -340,7 +423,6 @@ controls available in response bodies rather than hardcoding URLs.
 
 =head3 Assets
 
-    GET /assets?query=<JSON>
     POST /assets
         search for assets using L</JSON searches> syntax
 
@@ -364,7 +446,6 @@ controls available in response bodies rather than hardcoding URLs.
     GET /catalogs/all
         retrieve list of all catalogs you can see
 
-    GET /catalogs?query=<JSON>
     POST /catalogs
         search for catalogs using L</JSON searches> syntax
 
@@ -385,7 +466,6 @@ controls available in response bodies rather than hardcoding URLs.
 
 =head3 Users
 
-    GET /users?query=<JSON>
     POST /users
         search for users using L</JSON searches> syntax
 
@@ -410,7 +490,6 @@ controls available in response bodies rather than hardcoding URLs.
 
 =head3 Groups
 
-    GET /groups?query=<JSON>
     POST /groups
         search for groups using L</JSON searches> syntax
 
@@ -422,7 +501,6 @@ controls available in response bodies rather than hardcoding URLs.
 
 =head3 Custom Fields
 
-    GET /customfields?query=<JSON>
     POST /customfields
         search for custom fields using L</JSON searches> syntax
 
@@ -431,7 +509,6 @@ controls available in response bodies rather than hardcoding URLs.
 
 =head3 Custom Roles
 
-    GET /customroles?query=<JSON>
     POST /customroles
         search for custom roles using L</JSON searches> syntax
 

-----------------------------------------------------------------------


More information about the Bps-public-commit mailing list