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>