refs #13200 Merge branch '13200-new-package-versioning-jb'
[arvados.git] / doc / api / requests.html.textile.liquid
1 ---
2 layout: default
3 navsection: api
4 navmenu: Concepts
5 title: REST API syntax
6 ...
7 {% comment %}
8 Copyright (C) The Arvados Authors. All rights reserved.
9
10 SPDX-License-Identifier: CC-BY-SA-3.0
11 {% endcomment %}
12
13 Arvados exposes a REST API using standard HTTP requests.
14
15 h3. HTTP Method
16
17 Use @GET@ to request individual resources or lists of resources.
18
19 Use @POST@ to create new resources.
20
21 Use @PUT@ to update an existing resource.
22
23 Use @DELETE@ to remove an existing resource.
24
25 As a special case, a @POST@ with the query parameter @_method=GET@ will be treated as a GET request.  This makes it possible to issue @GET@ requests where the query string exceeds the maximum request URI length, by putting the query string in the body of the request.
26
27 h3. Request URI
28
29 The URI portion of the request identifies the specific resource to operate on.  For example, operations on "collections":{{site.baseurl}}/api/methods/collections.html use the @https://{{ site.arvados_api_host }}/arvados/v1/collections@ request URI prefix.
30
31 h3. Authorization header
32
33 Every request must include an API token.  This identifies the user making the request for the purposes of access control.  In addition, tokens may be further "restricted in scope":{{site.baseurl}}/api/methods/api_client_authorizations.html#scope to only access certain API endpoints.
34
35 API requests must provide the API token using the @Authorization@ header in the following format:
36
37 <pre>
38 $ curl -v -H "Authorization: OAuth2 xxxxapitokenxxxx" https://192.168.5.2:8000/arvados/v1/collections
39 > GET /arvados/v1/collections HTTP/1.1
40 > ...
41 > Authorization: OAuth2 xxxxapitokenxxxx
42 > ...
43 </pre>
44
45 h3. Parameters
46
47 Request parameters may be provided in one of two ways.  They may be provided in the "query" section of request URI, or they may be provided in the body of the request with application/x-www-form-urlencoded encoding.  If parameters are provided in both places, their values will be merged.  Parameter names must be unique.  If a parameter appears multiple times, the behavior is undefined.
48
49 Structured and nested parameter values must be provided as urlencoded JSON.
50
51 h3. Result
52
53 Results are returned JSON-encoded in the response body.
54
55 h3. Errors
56
57 If a request cannot be fulfilled, the API will return 4xx or 5xx HTTP status code.  Be aware that the API server may return a 404 (Not Found) status for resources that exist but for which the client does not have read access.  The API will also return an error record:
58
59 table(table table-bordered table-condensed).
60 |*Parameter name*|*Value*|*Description*|
61 |errors|array|An array of one or more error messages|
62 |error_token|string|a unique identifier used to correlate the error in the API server logs|
63
64 h2. Examples
65
66 h3. Create a new record
67
68 <pre>
69 $ curl -v -X POST --data-urlencode 'collection={"name":"empty collection"}' -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections | jq .
70 > POST /arvados/v1/collections HTTP/1.1
71 > User-Agent: curl/7.38.0
72 > Host: 192.168.5.2:8000
73 > Accept: */*
74 > Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
75 > Content-Length: 54
76 > Content-Type: application/x-www-form-urlencoded
77 >
78 } [data not shown]
79 < HTTP/1.1 200 OK
80 < Content-Type: application/json; charset=utf-8
81 < Transfer-Encoding: chunked
82 < Connection: keep-alive
83 < Status: 200 OK
84 < Access-Control-Allow-Origin: *
85 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
86 < Access-Control-Allow-Headers: Authorization
87 < Access-Control-Max-Age: 86486400
88 < X-UA-Compatible: IE=Edge,chrome=1
89 < ETag: "2ec9ef5151c1f7a1486ad169c33ae462"
90 < Cache-Control: max-age=0, private, must-revalidate
91 < Set-Cookie: _server_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFVEkiJTIwMjQ1NTE5YmEwMzU1MGZkMTBmYmY1YzllY2ZiMjFlBjsAVA%3D%3D--653bc9c20899d48ee8523e18d9a4c1cde0702577; path=/; HttpOnly
92 < X-Request-Id: 56aa10bc49097f3b44d3ed946bf0e61e
93 < X-Runtime: 0.049951
94 < X-Powered-By: Phusion Passenger 4.0.41
95 < Date: Fri, 28 Oct 2016 19:20:09 GMT
96 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
97 <
98 {
99   "href": "/collections/962eh-4zz18-m1ma0mxxfg3mbcc",
100   "kind": "arvados#collection",
101   "etag": "c5ifrv1ox2tu6alb559ymtkb7",
102   "uuid": "962eh-4zz18-m1ma0mxxfg3mbcc",
103   "owner_uuid": "962eh-tpzed-000000000000000",
104   "created_at": "2016-10-28T19:20:09.320771531Z",
105   "modified_by_client_uuid": "962eh-ozdt8-lm5x8emraox8epg",
106   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
107   "modified_at": "2016-10-28T19:20:09.319661000Z",
108   "name": "empty collection",
109   "description": null,
110   "properties": {},
111   "portable_data_hash": "d41d8cd98f00b204e9800998ecf8427e+0",
112   "manifest_text": "",
113   "replication_desired": null,
114   "replication_confirmed": null,
115   "replication_confirmed_at": null,
116   "expires_at": null
117 }
118 </pre>
119
120 h3. Delete a record
121
122 <pre>
123 $ curl -X DELETE -v -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-m1ma0mxxfg3mbcc | jq .
124 > DELETE /arvados/v1/collections/962eh-4zz18-m1ma0mxxfg3mbcc HTTP/1.1
125 > User-Agent: curl/7.38.0
126 > Host: 192.168.5.2:8000
127 > Accept: */*
128 > Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
129 >
130 < HTTP/1.1 200 OK
131 < Content-Type: application/json; charset=utf-8
132 < Transfer-Encoding: chunked
133 < Connection: keep-alive
134 < Status: 200 OK
135 < Access-Control-Allow-Origin: *
136 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
137 < Access-Control-Allow-Headers: Authorization
138 < Access-Control-Max-Age: 86486400
139 < X-UA-Compatible: IE=Edge,chrome=1
140 < ETag: "1e8f72802cf1a6d0a5c4a1ebbfcc46a9"
141 < Cache-Control: max-age=0, private, must-revalidate
142 < Set-Cookie: _server_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFVEkiJTc2NDYyY2M0NTNlNmU3M2Y2M2E3YmFiMWQ1MTEyZGZkBjsAVA%3D%3D--d28c7dd640bd24e2b12f01e77088072138dcf145; path=/; HttpOnly
143 < X-Request-Id: e66fd3ab825bdb87301f5456161fb641
144 < X-Runtime: 0.028788
145 < X-Powered-By: Phusion Passenger 4.0.41
146 < Date: Fri, 28 Oct 2016 19:33:31 GMT
147 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
148 <
149 {
150   "href": "/collections/962eh-4zz18-m1ma0mxxfg3mbcc",
151   "kind": "arvados#collection",
152   "etag": "c5ifrv1ox2tu6alb559ymtkb7",
153   "uuid": "962eh-4zz18-m1ma0mxxfg3mbcc",
154   "owner_uuid": "962eh-tpzed-000000000000000",
155   "created_at": "2016-10-28T19:20:09.320771000Z",
156   "modified_by_client_uuid": "962eh-ozdt8-lm5x8emraox8epg",
157   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
158   "modified_at": "2016-10-28T19:20:09.319661000Z",
159   "name": "empty collection",
160   "description": null,
161   "properties": {},
162   "portable_data_hash": "d41d8cd98f00b204e9800998ecf8427e+0",
163   "manifest_text": "",
164   "replication_desired": null,
165   "replication_confirmed": null,
166   "replication_confirmed_at": null,
167   "expires_at": null
168 }
169 </pre>
170
171 h3. Get a specific record
172
173 <pre>
174 $ curl -v -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km | jq .
175 > GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km HTTP/1.1
176 > User-Agent: curl/7.38.0
177 > Host: 192.168.5.2:8000
178 > Accept: */*
179 > Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
180 >
181 < HTTP/1.1 200 OK
182 < Content-Type: application/json; charset=utf-8
183 < Transfer-Encoding: chunked
184 < Connection: keep-alive
185 < Status: 200 OK
186 < Access-Control-Allow-Origin: *
187 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
188 < Access-Control-Allow-Headers: Authorization
189 < Access-Control-Max-Age: 86486400
190 < X-UA-Compatible: IE=Edge,chrome=1
191 < ETag: "fec2ddf433a352e5a2b5d356abd6d3d4"
192 < Cache-Control: max-age=0, private, must-revalidate
193 < X-Request-Id: 40b447507ff202ae9a0b0b3e0ebe98da
194 < X-Runtime: 0.011404
195 < X-Powered-By: Phusion Passenger 4.0.41
196 < Date: Fri, 28 Oct 2016 18:59:09 GMT
197 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
198 <
199 {
200   "href": "/collections/962eh-4zz18-xi32mpz2621o8km",
201   "kind": "arvados#collection",
202   "etag": "3mmn0s9e1z5s5opfofmtb9k8p",
203   "uuid": "962eh-4zz18-xi32mpz2621o8km",
204   "owner_uuid": "962eh-tpzed-000000000000000",
205   "created_at": "2016-10-27T14:47:43.792587000Z",
206   "modified_by_client_uuid": "962eh-ozdt8-lm5x8emraox8epg",
207   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
208   "modified_at": "2016-10-27T14:47:43.792166000Z",
209   "name": "Saved at 2016-10-27 14:47:43 UTC by peter@debian",
210   "description": null,
211   "properties": {},
212   "portable_data_hash": "93a45073511646a5c3e2f4953fcf6f61+116",
213   "manifest_text": ". eff999f3b5158331eb44a9a93e3b36e1+67108864+Aad3839bea88bce22cbfe71cf4943de7dab3ea52a@5826180f db141bfd11f7da60dce9e5ee85a988b8+34038725+Ae8f48913fed782cbe463e0499ab37697ee06a2f8@5826180f 0:101147589:rna.SRR948778.bam\n",
214   "replication_desired": null,
215   "replication_confirmed": null,
216   "replication_confirmed_at": null,
217   "expires_at": null
218 }
219 </pre>
220
221 h3. List records and filter by date
222
223 (Note, return result is truncated).
224
225 <pre>
226 $ curl -v -G --data-urlencode 'filters=[["created_at",">","2016-11-08T21:38:24.124834000Z"]]' -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections | jq .
227 > GET /arvados/v1/collections?filters=%5B%5B%22uuid%22%2C%20%22%3D%22%2C%20%22962eh-4zz18-xi32mpz2621o8km%22%5D%5D HTTP/1.1
228 > User-Agent: curl/7.38.0
229 > Host: 192.168.5.2:8000
230 > Accept: */*
231 > Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
232 >
233 < HTTP/1.1 200 OK
234 < Content-Type: application/json; charset=utf-8
235 < Transfer-Encoding: chunked
236 < Connection: keep-alive
237 < Status: 200 OK
238 < Access-Control-Allow-Origin: *
239 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
240 < Access-Control-Allow-Headers: Authorization
241 < Access-Control-Max-Age: 86486400
242 < X-UA-Compatible: IE=Edge,chrome=1
243 < ETag: "76345ef24952f073acc3a0c550241d4e"
244 < Cache-Control: max-age=0, private, must-revalidate
245 < X-Request-Id: d34b8ede4ffc707d8ed172dc2f47ff5e
246 < X-Runtime: 0.012727
247 < X-Powered-By: Phusion Passenger 4.0.41
248 < Date: Fri, 28 Oct 2016 19:08:52 GMT
249 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
250 <
251 {
252   "kind": "arvados#collectionList",
253   "etag": "",
254   "self_link": "",
255   "offset": 0,
256   "limit": 100,
257   "items": [
258     {
259       "href": "/collections/962eh-4zz18-ybggo9im899vv60",
260       "kind": "arvados#collection",
261       "etag": "bvgrrsg63zsenb9wnpnp0nsgl",
262       "uuid": "962eh-4zz18-ybggo9im899vv60",
263       "owner_uuid": "962eh-tpzed-000000000000000",
264       "created_at": "2016-11-08T21:47:36.937106000Z",
265       "modified_by_client_uuid": null,
266       "modified_by_user_uuid": "962eh-tpzed-000000000000000",
267       "modified_at": "2016-11-08T21:47:36.936625000Z",
268       "name": "Log from cwl-runner job 962eh-8i9sb-45jww0k15fi5ldd",
269       "description": null,
270       "properties": {},
271       "portable_data_hash": "a7820b94717eff86229927565fedbd72+85",
272       "replication_desired": null,
273       "replication_confirmed": null,
274       "replication_confirmed_at": null,
275       "expires_at": null
276     },
277    ...
278     {
279       "href": "/collections/962eh-4zz18-37i1tfl5de5ild9",
280       "kind": "arvados#collection",
281       "etag": "2fa07dx52lux8wa1loehwyrc5",
282       "uuid": "962eh-4zz18-37i1tfl5de5ild9",
283       "owner_uuid": "962eh-tpzed-000000000000000",
284       "created_at": "2016-11-08T21:38:46.717798000Z",
285       "modified_by_client_uuid": null,
286       "modified_by_user_uuid": "962eh-tpzed-000000000000000",
287       "modified_at": "2016-11-08T21:38:46.717409000Z",
288       "name": null,
289       "description": null,
290       "properties": {},
291       "portable_data_hash": "9d43d4c8328640446f6e252cda584e7e+54",
292       "replication_desired": null,
293       "replication_confirmed": null,
294       "replication_confirmed_at": null,
295       "expires_at": null
296     }
297   ],
298   "items_available": 99
299 }
300 </pre>
301
302 h3. Update a field
303
304 <pre>
305 $ curl -v -X PUT --data-urlencode 'collection={"name":"rna.SRR948778.bam"}' -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km | jq .
306 > PUT /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km HTTP/1.1
307 > User-Agent: curl/7.38.0
308 > Host: 192.168.5.2:8000
309 > Accept: */*
310 > Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
311 > Content-Length: 53
312 > Content-Type: application/x-www-form-urlencoded
313 >
314 } [data not shown]
315 < HTTP/1.1 200 OK
316 < Content-Type: application/json; charset=utf-8
317 < Transfer-Encoding: chunked
318 < Connection: keep-alive
319 < Status: 200 OK
320 < Access-Control-Allow-Origin: *
321 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
322 < Access-Control-Allow-Headers: Authorization
323 < Access-Control-Max-Age: 86486400
324 < X-UA-Compatible: IE=Edge,chrome=1
325 < ETag: "fbb50d2847426eab793e3fcf346ca9eb"
326 < Cache-Control: max-age=0, private, must-revalidate
327 < Set-Cookie: _server_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFVEkiJWI3NjFjMzVjMGI5OGExYmNjZDg0ZTg5MjZhMzcwMDE1BjsAVA%3D%3D--0e005d71fad15cb366e47361c38474b7447ba155; path=/; HttpOnly
328 < X-Request-Id: 76d3cb3c0995af6133b0a73a64f57354
329 < X-Runtime: 0.030756
330 < X-Powered-By: Phusion Passenger 4.0.41
331 < Date: Fri, 28 Oct 2016 19:15:16 GMT
332 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
333 <
334 {
335   "href": "/collections/962eh-4zz18-xi32mpz2621o8km",
336   "kind": "arvados#collection",
337   "etag": "51509hhxo9qqjxqewnoz1b7og",
338   "uuid": "962eh-4zz18-xi32mpz2621o8km",
339   "owner_uuid": "962eh-tpzed-000000000000000",
340   "created_at": "2016-10-27T14:47:43.792587000Z",
341   "modified_by_client_uuid": "962eh-ozdt8-lm5x8emraox8epg",
342   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
343   "modified_at": "2016-10-28T19:15:16.137814000Z",
344   "name": "rna.SRR948778.bam",
345   "description": null,
346   "properties": {},
347   "portable_data_hash": "93a45073511646a5c3e2f4953fcf6f61+116",
348   "manifest_text": ". eff999f3b5158331eb44a9a93e3b36e1+67108864+Acca57af82cc18c5dfa47bdfd16e335fccd09dfa5@582618c4 db141bfd11f7da60dce9e5ee85a988b8+34038725+A7764f122f41f92c2d5bde1852fcdd1bea5f8bd78@582618c4 0:101147589:rna.SRR948778.bam\n",
349   "replication_desired": null,
350   "replication_confirmed": null,
351   "replication_confirmed_at": null,
352   "expires_at": null
353 }
354 </pre>