Merge branch '19792-pysdk-cookbook'
[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: Bearer xxxxapitokenxxxx" https://192.168.5.2:8000/arvados/v1/collections
39 > GET /arvados/v1/collections HTTP/1.1
40 > ...
41 > Authorization: Bearer xxxxapitokenxxxx
42 > ...
43 </pre>
44
45 On a cluster configured to use an OpenID Connect provider (other than Google) as a login backend, Arvados can be configured to accept an OpenID Connect access token in place of an Arvados API token. OIDC access tokens are also accepted by a cluster that delegates login to another cluster (LoginCluster) which in turn has this feature configured. See @Login.OpenIDConnect.AcceptAccessTokenScope@ in the "default config.yml file":{{site.baseurl}}/admin/config.html for details.
46
47 <pre>
48 $ curl -v -H "Authorization: Bearer xxxx-openid-connect-access-token-xxxx" https://192.168.5.2:8000/arvados/v1/collections
49 </pre>
50
51 h3. Parameters
52
53 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.
54
55 Structured and nested parameter values must be provided as urlencoded JSON.
56
57 h3. Result
58
59 Results are returned JSON-encoded in the response body.
60
61 h3(#errors). Errors
62
63 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:
64
65 table(table table-bordered table-condensed).
66 |*Parameter name*|*Value*|*Description*|
67 |errors|array|An array of one or more error messages|
68 |error_token|string|a unique identifier used to correlate the error in the API server logs|
69
70 h2. Examples
71
72 h3. Create a new record
73
74 <pre>
75 $ curl -v -X POST --data-urlencode 'collection={"name":"empty collection"}' -H "Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections | jq .
76 > POST /arvados/v1/collections HTTP/1.1
77 > User-Agent: curl/7.38.0
78 > Host: 192.168.5.2:8000
79 > Accept: */*
80 > Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
81 > Content-Length: 54
82 > Content-Type: application/x-www-form-urlencoded
83 >
84 } [data not shown]
85 < HTTP/1.1 200 OK
86 < Content-Type: application/json; charset=utf-8
87 < Transfer-Encoding: chunked
88 < Connection: keep-alive
89 < Status: 200 OK
90 < Access-Control-Allow-Origin: *
91 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
92 < Access-Control-Allow-Headers: Authorization
93 < Access-Control-Max-Age: 86486400
94 < X-UA-Compatible: IE=Edge,chrome=1
95 < ETag: "2ec9ef5151c1f7a1486ad169c33ae462"
96 < Cache-Control: max-age=0, private, must-revalidate
97 < Set-Cookie: _server_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFVEkiJTIwMjQ1NTE5YmEwMzU1MGZkMTBmYmY1YzllY2ZiMjFlBjsAVA%3D%3D--653bc9c20899d48ee8523e18d9a4c1cde0702577; path=/; HttpOnly
98 < X-Request-Id: 56aa10bc49097f3b44d3ed946bf0e61e
99 < X-Runtime: 0.049951
100 < X-Powered-By: Phusion Passenger 4.0.41
101 < Date: Fri, 28 Oct 2016 19:20:09 GMT
102 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
103 <
104 {
105   "href": "/collections/962eh-4zz18-m1ma0mxxfg3mbcc",
106   "kind": "arvados#collection",
107   "etag": "c5ifrv1ox2tu6alb559ymtkb7",
108   "uuid": "962eh-4zz18-m1ma0mxxfg3mbcc",
109   "owner_uuid": "962eh-tpzed-000000000000000",
110   "created_at": "2016-10-28T19:20:09.320771531Z",
111   "modified_by_client_uuid": "962eh-ozdt8-lm5x8emraox8epg",
112   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
113   "modified_at": "2016-10-28T19:20:09.319661000Z",
114   "name": "empty collection",
115   "description": null,
116   "properties": {},
117   "portable_data_hash": "d41d8cd98f00b204e9800998ecf8427e+0",
118   "manifest_text": "",
119   "replication_desired": null,
120   "replication_confirmed": null,
121   "replication_confirmed_at": null,
122   "expires_at": null
123 }
124 </pre>
125
126 h3. Delete a record
127
128 <pre>
129 $ curl -X DELETE -v -H "Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-m1ma0mxxfg3mbcc | jq .
130 > DELETE /arvados/v1/collections/962eh-4zz18-m1ma0mxxfg3mbcc HTTP/1.1
131 > User-Agent: curl/7.38.0
132 > Host: 192.168.5.2:8000
133 > Accept: */*
134 > Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
135 >
136 < HTTP/1.1 200 OK
137 < Content-Type: application/json; charset=utf-8
138 < Transfer-Encoding: chunked
139 < Connection: keep-alive
140 < Status: 200 OK
141 < Access-Control-Allow-Origin: *
142 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
143 < Access-Control-Allow-Headers: Authorization
144 < Access-Control-Max-Age: 86486400
145 < X-UA-Compatible: IE=Edge,chrome=1
146 < ETag: "1e8f72802cf1a6d0a5c4a1ebbfcc46a9"
147 < Cache-Control: max-age=0, private, must-revalidate
148 < Set-Cookie: _server_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFVEkiJTc2NDYyY2M0NTNlNmU3M2Y2M2E3YmFiMWQ1MTEyZGZkBjsAVA%3D%3D--d28c7dd640bd24e2b12f01e77088072138dcf145; path=/; HttpOnly
149 < X-Request-Id: e66fd3ab825bdb87301f5456161fb641
150 < X-Runtime: 0.028788
151 < X-Powered-By: Phusion Passenger 4.0.41
152 < Date: Fri, 28 Oct 2016 19:33:31 GMT
153 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
154 <
155 {
156   "href": "/collections/962eh-4zz18-m1ma0mxxfg3mbcc",
157   "kind": "arvados#collection",
158   "etag": "c5ifrv1ox2tu6alb559ymtkb7",
159   "uuid": "962eh-4zz18-m1ma0mxxfg3mbcc",
160   "owner_uuid": "962eh-tpzed-000000000000000",
161   "created_at": "2016-10-28T19:20:09.320771000Z",
162   "modified_by_client_uuid": "962eh-ozdt8-lm5x8emraox8epg",
163   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
164   "modified_at": "2016-10-28T19:20:09.319661000Z",
165   "name": "empty collection",
166   "description": null,
167   "properties": {},
168   "portable_data_hash": "d41d8cd98f00b204e9800998ecf8427e+0",
169   "manifest_text": "",
170   "replication_desired": null,
171   "replication_confirmed": null,
172   "replication_confirmed_at": null,
173   "expires_at": null
174 }
175 </pre>
176
177 h3. Get a specific record
178
179 <pre>
180 $ curl -v -H "Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km | jq .
181 > GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km HTTP/1.1
182 > User-Agent: curl/7.38.0
183 > Host: 192.168.5.2:8000
184 > Accept: */*
185 > Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
186 >
187 < HTTP/1.1 200 OK
188 < Content-Type: application/json; charset=utf-8
189 < Transfer-Encoding: chunked
190 < Connection: keep-alive
191 < Status: 200 OK
192 < Access-Control-Allow-Origin: *
193 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
194 < Access-Control-Allow-Headers: Authorization
195 < Access-Control-Max-Age: 86486400
196 < X-UA-Compatible: IE=Edge,chrome=1
197 < ETag: "fec2ddf433a352e5a2b5d356abd6d3d4"
198 < Cache-Control: max-age=0, private, must-revalidate
199 < X-Request-Id: 40b447507ff202ae9a0b0b3e0ebe98da
200 < X-Runtime: 0.011404
201 < X-Powered-By: Phusion Passenger 4.0.41
202 < Date: Fri, 28 Oct 2016 18:59:09 GMT
203 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
204 <
205 {
206   "href": "/collections/962eh-4zz18-xi32mpz2621o8km",
207   "kind": "arvados#collection",
208   "etag": "3mmn0s9e1z5s5opfofmtb9k8p",
209   "uuid": "962eh-4zz18-xi32mpz2621o8km",
210   "owner_uuid": "962eh-tpzed-000000000000000",
211   "created_at": "2016-10-27T14:47:43.792587000Z",
212   "modified_by_client_uuid": "962eh-ozdt8-lm5x8emraox8epg",
213   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
214   "modified_at": "2016-10-27T14:47:43.792166000Z",
215   "name": "Saved at 2016-10-27 14:47:43 UTC by peter@debian",
216   "description": null,
217   "properties": {},
218   "portable_data_hash": "93a45073511646a5c3e2f4953fcf6f61+116",
219   "manifest_text": ". eff999f3b5158331eb44a9a93e3b36e1+67108864+Aad3839bea88bce22cbfe71cf4943de7dab3ea52a@5826180f db141bfd11f7da60dce9e5ee85a988b8+34038725+Ae8f48913fed782cbe463e0499ab37697ee06a2f8@5826180f 0:101147589:rna.SRR948778.bam\n",
220   "replication_desired": null,
221   "replication_confirmed": null,
222   "replication_confirmed_at": null,
223   "expires_at": null
224 }
225 </pre>
226
227 h3. List records and filter by date
228
229 (Note, return result is truncated).
230
231 <pre>
232 $ curl -v -G --data-urlencode 'filters=[["created_at",">","2016-11-08T21:38:24.124834000Z"]]' -H "Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections | jq .
233 > 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
234 > User-Agent: curl/7.38.0
235 > Host: 192.168.5.2:8000
236 > Accept: */*
237 > Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
238 >
239 < HTTP/1.1 200 OK
240 < Content-Type: application/json; charset=utf-8
241 < Transfer-Encoding: chunked
242 < Connection: keep-alive
243 < Status: 200 OK
244 < Access-Control-Allow-Origin: *
245 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
246 < Access-Control-Allow-Headers: Authorization
247 < Access-Control-Max-Age: 86486400
248 < X-UA-Compatible: IE=Edge,chrome=1
249 < ETag: "76345ef24952f073acc3a0c550241d4e"
250 < Cache-Control: max-age=0, private, must-revalidate
251 < X-Request-Id: d34b8ede4ffc707d8ed172dc2f47ff5e
252 < X-Runtime: 0.012727
253 < X-Powered-By: Phusion Passenger 4.0.41
254 < Date: Fri, 28 Oct 2016 19:08:52 GMT
255 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
256 <
257 {
258   "kind": "arvados#collectionList",
259   "etag": "",
260   "self_link": "",
261   "offset": 0,
262   "limit": 100,
263   "items": [
264     {
265       "href": "/collections/962eh-4zz18-ybggo9im899vv60",
266       "kind": "arvados#collection",
267       "etag": "bvgrrsg63zsenb9wnpnp0nsgl",
268       "uuid": "962eh-4zz18-ybggo9im899vv60",
269       "owner_uuid": "962eh-tpzed-000000000000000",
270       "created_at": "2016-11-08T21:47:36.937106000Z",
271       "modified_by_client_uuid": null,
272       "modified_by_user_uuid": "962eh-tpzed-000000000000000",
273       "modified_at": "2016-11-08T21:47:36.936625000Z",
274       "name": "Log from cwl-runner job 962eh-8i9sb-45jww0k15fi5ldd",
275       "description": null,
276       "properties": {},
277       "portable_data_hash": "a7820b94717eff86229927565fedbd72+85",
278       "replication_desired": null,
279       "replication_confirmed": null,
280       "replication_confirmed_at": null,
281       "expires_at": null
282     },
283    ...
284     {
285       "href": "/collections/962eh-4zz18-37i1tfl5de5ild9",
286       "kind": "arvados#collection",
287       "etag": "2fa07dx52lux8wa1loehwyrc5",
288       "uuid": "962eh-4zz18-37i1tfl5de5ild9",
289       "owner_uuid": "962eh-tpzed-000000000000000",
290       "created_at": "2016-11-08T21:38:46.717798000Z",
291       "modified_by_client_uuid": null,
292       "modified_by_user_uuid": "962eh-tpzed-000000000000000",
293       "modified_at": "2016-11-08T21:38:46.717409000Z",
294       "name": null,
295       "description": null,
296       "properties": {},
297       "portable_data_hash": "9d43d4c8328640446f6e252cda584e7e+54",
298       "replication_desired": null,
299       "replication_confirmed": null,
300       "replication_confirmed_at": null,
301       "expires_at": null
302     }
303   ],
304   "items_available": 99
305 }
306 </pre>
307
308 h3. Update a field
309
310 <pre>
311 $ curl -v -X PUT --data-urlencode 'collection={"name":"rna.SRR948778.bam"}' -H "Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km | jq .
312 > PUT /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km HTTP/1.1
313 > User-Agent: curl/7.38.0
314 > Host: 192.168.5.2:8000
315 > Accept: */*
316 > Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
317 > Content-Length: 53
318 > Content-Type: application/x-www-form-urlencoded
319 >
320 } [data not shown]
321 < HTTP/1.1 200 OK
322 < Content-Type: application/json; charset=utf-8
323 < Transfer-Encoding: chunked
324 < Connection: keep-alive
325 < Status: 200 OK
326 < Access-Control-Allow-Origin: *
327 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
328 < Access-Control-Allow-Headers: Authorization
329 < Access-Control-Max-Age: 86486400
330 < X-UA-Compatible: IE=Edge,chrome=1
331 < ETag: "fbb50d2847426eab793e3fcf346ca9eb"
332 < Cache-Control: max-age=0, private, must-revalidate
333 < Set-Cookie: _server_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFVEkiJWI3NjFjMzVjMGI5OGExYmNjZDg0ZTg5MjZhMzcwMDE1BjsAVA%3D%3D--0e005d71fad15cb366e47361c38474b7447ba155; path=/; HttpOnly
334 < X-Request-Id: 76d3cb3c0995af6133b0a73a64f57354
335 < X-Runtime: 0.030756
336 < X-Powered-By: Phusion Passenger 4.0.41
337 < Date: Fri, 28 Oct 2016 19:15:16 GMT
338 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
339 <
340 {
341   "href": "/collections/962eh-4zz18-xi32mpz2621o8km",
342   "kind": "arvados#collection",
343   "etag": "51509hhxo9qqjxqewnoz1b7og",
344   "uuid": "962eh-4zz18-xi32mpz2621o8km",
345   "owner_uuid": "962eh-tpzed-000000000000000",
346   "created_at": "2016-10-27T14:47:43.792587000Z",
347   "modified_by_client_uuid": "962eh-ozdt8-lm5x8emraox8epg",
348   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
349   "modified_at": "2016-10-28T19:15:16.137814000Z",
350   "name": "rna.SRR948778.bam",
351   "description": null,
352   "properties": {},
353   "portable_data_hash": "93a45073511646a5c3e2f4953fcf6f61+116",
354   "manifest_text": ". eff999f3b5158331eb44a9a93e3b36e1+67108864+Acca57af82cc18c5dfa47bdfd16e335fccd09dfa5@582618c4 db141bfd11f7da60dce9e5ee85a988b8+34038725+A7764f122f41f92c2d5bde1852fcdd1bea5f8bd78@582618c4 0:101147589:rna.SRR948778.bam\n",
355   "replication_desired": null,
356   "replication_confirmed": null,
357   "replication_confirmed_at": null,
358   "expires_at": null
359 }
360 </pre>