[Bps-public-commit] rt-extension-rest2 branch, rt-extension-rest2-docs, repushed

[Craig Kaiser]

The branch rt-extension-rest2-docs was deleted and repushed:
       was 09d7e3f51a26e2e50df674fb6b5e342f6656ffbf
       now e7acf97dc4eb28f449c11ce18d96585966bc00e9

1:  09d7e3f ! 1:  e7acf97 Remove incorrect JSON query documentation
    @@ -1,131 +1,12 @@
     Author: Craig Kaiser <craig at bestpractical.com>
     
    -    Update REST2 docs with examples and clearer notation
    +    Remove incorrect JSON query documentation
         
    -    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.
    +    Only the tickets endpoint supports JSON queries for a GET request.
     
     diff --git a/lib/RT/Extension/REST2.pm b/lib/RT/Extension/REST2.pm
     --- a/lib/RT/Extension/REST2.pm
     +++ b/lib/RT/Extension/REST2.pm
    -@@
    - 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 endpoints 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"
    -+        },
    -+    ]}
    -+
    -+Query our Group id = 2:
    -+
    -+    curl -X GET -u 'root:password' 'REST/2.0/group/2/'
    -+
    -+Here we can get the information on group 2:
    -+
    -+     "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
    -+
    -+Use POST method to submit JSON data.
    -+
    -+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>.
    -@@
    -         "id"   : "20"
    -     }
    - 
    -+With CustomFields:
    -+
    -+    curl -X POST -H "Content-Type: application/json"
    -+        -d '{"Subject": "Ticket Create using REST", "CustomFields": {"MyCustomField": "value"} }'
    -+        -u 'root:password'
    -+        '/REST/2.0/ticket?Queue=1'
    -+
    -+Result:
    -+
    -+    {"_url":"/REST/2.0/ticket/1","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)
    -@@
    -          -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
     @@
      
      =head3 Transactions
    @@ -190,12 +71,8 @@
          POST /customfields
              search for custom fields using L</JSON searches> syntax
      
    -     GET /customfield/:id
    -         retrieve a custom field
    +@@
      
    -+    POST or PUT with CustomFields
    -+        JSON { "CustomFields": {"CustomFieldName": "value", "CustomFieldName": "value"} }
    -+
      =head3 Custom Roles
      
     -    GET /customroles?query=<JSON>