[Bps-public-commit] rt-extension-rest2 branch, rt-extension-rest2-docs, created. 1.01-1-g09d7e3f
Craig Kaiser
craig at bestpractical.com
Wed Feb 14 13:01:57 EST 2018
The branch, rt-extension-rest2-docs has been created
at 09d7e3f51a26e2e50df674fb6b5e342f6656ffbf (commit)
- Log -----------------------------------------------------------------
commit 09d7e3f51a26e2e50df674fb6b5e342f6656ffbf
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..654c442 100644
--- a/lib/RT/Extension/REST2.pm
+++ b/lib/RT/Extension/REST2.pm
@@ -138,6 +138,83 @@ 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 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>.
@@ -162,6 +239,17 @@ If successful, that will provide output like so:
"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)
@@ -194,6 +282,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 +374,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 +391,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 +405,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 +429,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 +452,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 +472,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 +496,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,16 +507,17 @@ 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
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>
POST /customroles
search for custom roles using L</JSON searches> syntax
-----------------------------------------------------------------------
More information about the Bps-public-commit
mailing list