forked from bestpractical/rt-extension-rest2
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
565 lines (438 loc) · 19.5 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
NAME
RT::Extension::REST2 - Adds a modern REST API to RT under /REST/2.0/
INSTALLATION
perl Makefile.PL
make
make install
May need root permissions
Edit your /opt/rt4/etc/RT_SiteConfig.pm
Add this line:
Plugin('RT::Extension::REST2');
Clear your mason cache
rm -rf /opt/rt4/var/mason_data/obj
Restart your webserver
USAGE
Tutorial
To make it easier to authenticate to REST2, we recommend installing
RT::Authen::Token. Visit "Logged in as ___" -> Settings -> Auth Tokens.
Create an Auth Token, give it any description (such as "REST2 with
curl"). Make note of the authentication token it provides to you.
For other authentication options see the section "Authentication
Methods" below.
Authentication
Run the following in a terminal, filling in XX_TOKEN_XX from the auth
token above and XX_RT_URL_XX with the URL for your RT instance.
curl -H 'Authorization: token XX_TOKEN_XX' 'XX_RT_URL_XX/REST/2.0/queues/all'
This does an authenticated request (using the Authorization HTTP header
with type token) for all of the queues you can see. You should see a
response, typical of search results, like this:
{
"total" : 1,
"count" : 1,
"page" : 1,
"per_page" : 20,
"items" : [
{
"type" : "queue",
"id" : "1",
"_url" : "XX_RT_URL_XX/REST/2.0/queue/1"
}
]
}
This format is JSON, which is a format for which many programming
languages provide libraries for parsing and generating.
(If you instead see a response like {"message":"Unauthorized"} that
indicates RT couldn't process your authentication token successfully;
make sure the word "token" appears between "Authorization:" and the auth
token that RT provided to you)
Following Links
You can request one of the provided _urls to get more information about
that queue.
curl -H 'Authorization: token XX_TOKEN_XX' 'XX_QUEUE_URL_XX'
This will give a lot of information, like so:
{
"id" : 1,
"Name" : "General",
"Description" : "The default queue",
"Lifecycle" : "default",
...
"CustomFields" : {},
"_hyperlinks" : [
{
"id" : "1",
"ref" : "self",
"type" : "queue",
"_url" : "XX_RT_URL_XX/REST/2.0/queue/1"
},
{
"ref" : "history",
"_url" : "XX_RT_URL_XX/REST/2.0/queue/1/history"
},
{
"ref" : "create",
"type" : "ticket",
"_url" : "XX_RT_URL_XX/REST/2.0/ticket?Queue=1"
}
],
}
Of particular note is the _hyperlinks key, which gives you a list of
related resources to examine (following the
<https://en.wikipedia.org/wiki/HATEOAS> principle). For example an entry
with a ref of history lets you examine the transaction log for a record.
You can implement your REST API client knowing that any other hypermedia
link with a ref of history has the same meaning, regardless of whether
it's the history of a queue, ticket, asset, etc.
Another ref you'll see in _hyperlinks is create, with a type of ticket.
This of course gives you the URL to create tickets *in this queue*.
Importantly, if your user does *not* have the CreateTicket permission in
this queue, then REST2 would simply not 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.
Creating Tickets
Let's use the _url from the create hyperlink with type ticket.
To create a ticket is a bit more involved, since it requires providing a
different HTTP verb (POST instead of GET), a Content-Type header (to
tell REST2 that your content is JSON instead of, say, XML), and the
fields for your new ticket such as Subject. Here is the curl invocation,
wrapped to multiple lines for readability.
curl -X POST
-H "Content-Type: application/json"
-d '{ "Subject": "hello world" }'
-H 'Authorization: token XX_TOKEN_XX'
'XX_TICKET_CREATE_URL_XX'
If successful, that will provide output like so:
{
"_url" : "XX_RT_URL_XX/REST/2.0/ticket/20",
"type" : "ticket",
"id" : "20"
}
(REST2 also produces the status code of 201 Created with a Location
header of the new ticket, which you may choose to use instead of the
JSON response)
We can fetch that _url to continue working with this newly-created
ticket. Request the ticket like so (make sure to include the -i flag to
see response's HTTP headers).
curl -i -H 'Authorization: token XX_TOKEN_XX' 'XX_TICKET_URL_XX'
You'll first see that there are many hyperlinks for tickets, including
one for each Lifecycle action you can perform, history, comment,
correspond, etc. Again these adapt to whether you have the appropriate
permissions to do these actions.
Additionally you'll see an ETag header for this record, which can be
used for conflict avoidance (<https://en.wikipedia.org/wiki/HTTP_ETag>).
We'll first try updating this ticket with an *invalid* ETag to see what
happens.
Updating Tickets
For updating tickets we use the PUT verb, but otherwise it looks much
like a ticket creation.
curl -X PUT
-H "Content-Type: application/json"
-H "If-Match: invalid-etag"
-d '{ "Subject": "trial update" }'
-H 'Authorization: token XX_TOKEN_XX'
'XX_TICKET_URL_XX'
You'll get an error response like {"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 If-Match header advises
the server to make changes *if and only if* the ticket's ETag matches
what you provide. Since it differed, the server refused the request and
made no changes.
Now, try the same request by replacing the value "invalid-etag" in the
If-Match request header with the real ETag you'd received when you
requested the ticket previously. You'll then get a JSON response like:
["Ticket 1: Subject changed from 'hello world' to 'trial update'"]
which is a list of messages meant for displaying to an end-user.
If you GET the ticket again, you'll observe that the ETag header now has
a different value, indicating that the ticket itself has changed. This
means if you were to retry the PUT update with the previous (at the
time, expected) ETag you would instead be rejected by the server with
Precondition Failed.
You can use ETag and If-Match headers to avoid race conditions such as
two people updating a ticket at the same time. Depending on the
sophistication of your client, you may be able to automatically retry
the change by incorporating the changes made on the server (for example
adding time worked can be automatically be recalculated).
You may of course choose to ignore the ETag header and not provide
If-Match in your requests; RT doesn't require its use.
Summary
RT's REST2 API provides the tools you need to build robust and dynamic
integrations. Tools like ETag/If-Match allow you to avoid conflicts such
as two people taking a ticket at the same time. Using JSON for all data
interchange avoids problems caused by parsing text. Hypermedia links
inform your client application of what the user has the ability to do.
Careful readers will see that, other than our initial entry into the
system, we did not *generate* any URLs. We only *followed* links, just
like you do when browsing a website on your computer. We've better
decoupled the client's implementation from the server's REST API.
Additionally, this system lets you be informed of new capabilities in
the form of additional hyperlinks.
Using these tools and principles, REST2 will help you build rich,
robust, and powerful integrations with the other applications and
services that your team uses.
Endpoints
Currently provided endpoints under /REST/2.0/ are described below.
Wherever possible please consider using _hyperlinks hypermedia controls
available in response bodies rather than hardcoding URLs.
For simplicity, the examples below omit the extra options to curl for
SSL like --cacert.
Tickets
GET /tickets?query=<TicketSQL>
search for tickets using TicketSQL
GET /tickets?simple=1;query=<simple search query>
search for tickets using simple search syntax
POST /tickets
search for tickets with the 'query' and optional 'simple' parameters
POST /ticket
create a ticket; provide JSON content
GET /ticket/:id
retrieve a ticket
PUT /ticket/:id
update a ticket's metadata; provide JSON content
DELETE /ticket/:id
set status to deleted
POST /ticket/:id/correspond
POST /ticket/:id/comment
add a reply or comment to the ticket
GET /ticket/:id/history
retrieve list of transactions for ticket
POST /tickets/bulk
create multiple tickets; provide JSON content(array of hashes)
PUT /tickets/bulk
update multiple tickets' metadata; provide JSON content(array of hashes)
Ticket Examples
Below are some examples using the endpoints above.
# Create a ticket, setting some custom fields
curl -X POST -H "Content-Type: application/json" -u 'root:password'
-d '{ "Queue": "General", "Subject": "Create ticket test",
"From": "[email protected]", "To": "[email protected]",
"Content": "Testing a create",
"CustomFields": {"Severity": "Low"}}'
'https://myrt.com/REST/2.0/ticket'
# Update a ticket, with a custom field update
curl -X PUT -H "Content-Type: application/json" -u 'root:password'
-d '{ "Subject": "Update test", "CustomFields": {"Severity": "High"}}'
'https://myrt.com/REST/2.0/ticket/6'
# Correspond a ticket
curl -X POST -H "Content-Type: application/json" -u 'root:password'
-d '{ "Content": "Testing a correspondence", "ContentType": "text/plain" }'
'https://myrt.com/REST/2.0/ticket/6/correspond'
# Comment a ticket
curl -X POST -H "Content-Type: text/plain" -u 'root:password'
-d 'Testing a comment'
'https://myrt.com/REST/2.0/ticket/6/comment'
# Create an Asset
curl -X POST -H "Content-Type: application/json" -u 'root:password'
-d '{"Name" : "Asset From Rest", "Catalog" : "General assets", "Content" : "Some content"}'
'https://myrt.com/REST/2.0/asset'
# Search Assets
curl -X POST -H "Content-Type: application/json" -u 'root:password'
-d '[{ "field" : "id", "operator" : ">=", "value" : 0 }]'
'https://myrt.com/REST/2.0/asset'
Transactions
GET /transactions?query=<JSON>
POST /transactions
search for transactions using L</JSON searches> syntax
GET /ticket/:id/history
GET /queue/:id/history
GET /queue/:name/history
GET /asset/:id/history
GET /user/:id/history
GET /user/:name/history
GET /group/:id/history
get transactions for record
GET /transaction/:id
retrieve a transaction
Attachments and Messages
GET /attachments?query=<JSON>
POST /attachments
search for attachments using L</JSON searches> syntax
GET /transaction/:id/attachments
get attachments for transaction
GET /attachment/:id
retrieve an attachment
Queues
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
POST /queue
create a queue; provide JSON content
GET /queue/:id
GET /queue/:name
retrieve a queue by numeric id or name
PUT /queue/:id
PUT /queue/:name
update a queue's metadata; provide JSON content
DELETE /queue/:id
DELETE /queue/:name
disable queue
GET /queue/:id/history
GET /queue/:name/history
retrieve list of transactions for queue
Assets
GET /assets?query=<JSON>
POST /assets
search for assets using L</JSON searches> syntax
POST /asset
create an asset; provide JSON content
GET /asset/:id
retrieve an asset
PUT /asset/:id
update an asset's metadata; provide JSON content
DELETE /asset/:id
set status to deleted
GET /asset/:id/history
retrieve list of transactions for asset
Catalogs
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
POST /catalog
create a catalog; provide JSON content
GET /catalog/:id
GET /catalog/:name
retrieve a catalog by numeric id or name
PUT /catalog/:id
PUT /catalog/:name
update a catalog's metadata; provide JSON content
DELETE /catalog/:id
DELETE /catalog/:name
disable catalog
Users
GET /users?query=<JSON>
POST /users
search for users using L</JSON searches> syntax
POST /user
create a user; provide JSON content
GET /user/:id
GET /user/:name
retrieve a user by numeric id or username
PUT /user/:id
PUT /user/:name
update a user's metadata; provide JSON content
DELETE /user/:id
DELETE /user/:name
disable user
GET /user/:id/history
GET /user/:name/history
retrieve list of transactions for user
Groups
GET /groups?query=<JSON>
POST /groups
search for groups using L</JSON searches> syntax
GET /group/:id
retrieve a group (including its members)
GET /group/:id/history
retrieve list of transactions for group
Custom Fields
GET /customfields?query=<JSON>
POST /customfields
search for custom fields using L</JSON searches> syntax
GET /customfield/:id
retrieve a custom field
Custom Roles
GET /customroles?query=<JSON>
POST /customroles
search for custom roles using L</JSON searches> syntax
GET /customrole/:id
retrieve a custom role
Miscellaneous
GET /
produces this documentation
GET /rt
produces system information
JSON searches
Some resources accept a basic JSON structure as the search conditions
which specifies one or more fields to limit on (using specified
operators and values). An example:
curl -si -u user:pass https://rt.example.com/REST/2.0/queues -XPOST --data-binary '
[
{ "field": "Name",
"operator": "LIKE",
"value": "Engineering" },
{ "field": "Lifecycle",
"value": "helpdesk" }
]
'
The JSON payload must be an array of hashes with the keys field and
value and optionally operator.
Results are returned in the format described below.
Example of plural resources (collections)
Resources which represent a collection of other resources use the
following standard JSON format:
{
"count" : 20,
"page" : 1,
"per_page" : 20,
"total" : 3810,
"items" : [
{ … },
{ … },
…
]
}
Each item is nearly the same representation used when an individual
resource is requested.
Paging
All plural resources (such as /tickets) require pagination, controlled
by the query parameters page and per_page. The default page size is 20
items, but it may be increased up to 100 (or decreased if desired). Page
numbers start at 1.
Authentication Methods
Authentication should always be done over HTTPS/SSL for security. You
should only serve up the /REST/2.0/ endpoint over SSL.
Basic Auth
Authentication may use internal RT usernames and passwords, provided via
HTTP Basic auth. Most HTTP libraries already have a way of providing
basic auth credentials when making requests. Using curl, for example:
curl -u 'username:password' /path/to/REST/2.0
Token Auth
You may use the RT::Authen::Token extension to authenticate to the REST
2 API. Once you've acquired an authentication token in the web
interface, specify the Authorization header with a value of "token" like
so:
curl -H 'Authorization: token …' /path/to/REST/2.0
If the library or application you're using does not support specifying
additional HTTP headers, you may also pass the authentication token as a
query parameter like so:
curl /path/to/REST/2.0?token=…
Cookie Auth
Finally, you may reuse an existing cookie from an ordinary web session
to authenticate against REST2. This is primarily intended for
interacting with REST2 via JavaScript in the browser. Other REST
consumers are advised to use the alternatives above.
Conditional requests (If-Modified-Since, If-Match)
You can take advantage of the Last-Modified headers returned by most
single resource endpoints. Add a If-Modified-Since header to your
requests for the same resource, using the most recent Last-Modified
value seen, and the API may respond with a 304 Not Modified. You can
also use HEAD requests to check for updates without receiving the actual
content when there is a newer version. You may also add an
If-Unmodified-Since header to your updates to tell the server to refuse
updates if the record had been changed since you last retrieved it.
ETag, If-Match, and If-None-Match work similarly to Last-Modified,
If-Modified-Since, and If-Unmodified-Since, except that they don't use a
timestamp, which has its own set of tradeoffs. ETag is an opaque value,
so it has no meaning to consumers (unlike timestamps). However,
timestamps have the disadvantage of having a resolution of seconds, so
two updates happening in the same second would produce incorrect
results, whereas ETag does not suffer from that problem.
Status codes
The REST API uses the full range of HTTP status codes, and your client
should handle them appropriately.
AUTHOR
Best Practical Solutions, LLC <[email protected]>
BUGS
All bugs should be reported via email to
<mailto:[email protected]> or via the web at
rt.cpan.org
<http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-REST2>.
LICENSE AND COPYRIGHT
This software is Copyright (c) 2015-2017 by Best Practical Solutions,
LLC.
This is free software, licensed under:
The GNU General Public License, Version 2, June 1991