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>