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   "kind": "arvados#collection",
 106   "etag": "c5ifrv1ox2tu6alb559ymtkb7",
 107   "uuid": "962eh-4zz18-m1ma0mxxfg3mbcc",
 108   "owner_uuid": "962eh-tpzed-000000000000000",
 109   "created_at": "2016-10-28T19:20:09.320771531Z",
 110   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
 111   "modified_at": "2016-10-28T19:20:09.319661000Z",
 112   "name": "empty collection",
 113   "description": null,
 114   "properties": {},
 115   "portable_data_hash": "d41d8cd98f00b204e9800998ecf8427e+0",
 116   "manifest_text": "",
 117   "replication_desired": null,
 118   "replication_confirmed": null,
 119   "replication_confirmed_at": null,
 120   "expires_at": null
 121 }
 122 </pre>
 123
 124 h3. Delete a record
 125
 126 <pre>
 127 $ curl -X DELETE -v -H "Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-m1ma0mxxfg3mbcc | jq .
 128 > DELETE /arvados/v1/collections/962eh-4zz18-m1ma0mxxfg3mbcc HTTP/1.1
 129 > User-Agent: curl/7.38.0
 130 > Host: 192.168.5.2:8000
 131 > Accept: */*
 132 > Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
 133 >
 134 < HTTP/1.1 200 OK
 135 < Content-Type: application/json; charset=utf-8
 136 < Transfer-Encoding: chunked
 137 < Connection: keep-alive
 138 < Status: 200 OK
 139 < Access-Control-Allow-Origin: *
 140 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
 141 < Access-Control-Allow-Headers: Authorization
 142 < Access-Control-Max-Age: 86486400
 143 < X-UA-Compatible: IE=Edge,chrome=1
 144 < ETag: "1e8f72802cf1a6d0a5c4a1ebbfcc46a9"
 145 < Cache-Control: max-age=0, private, must-revalidate
 146 < Set-Cookie: _server_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFVEkiJTc2NDYyY2M0NTNlNmU3M2Y2M2E3YmFiMWQ1MTEyZGZkBjsAVA%3D%3D--d28c7dd640bd24e2b12f01e77088072138dcf145; path=/; HttpOnly
 147 < X-Request-Id: e66fd3ab825bdb87301f5456161fb641
 148 < X-Runtime: 0.028788
 149 < X-Powered-By: Phusion Passenger 4.0.41
 150 < Date: Fri, 28 Oct 2016 19:33:31 GMT
 151 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
 152 <
 153 {
 154   "kind": "arvados#collection",
 155   "etag": "c5ifrv1ox2tu6alb559ymtkb7",
 156   "uuid": "962eh-4zz18-m1ma0mxxfg3mbcc",
 157   "owner_uuid": "962eh-tpzed-000000000000000",
 158   "created_at": "2016-10-28T19:20:09.320771000Z",
 159   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
 160   "modified_at": "2016-10-28T19:20:09.319661000Z",
 161   "name": "empty collection",
 162   "description": null,
 163   "properties": {},
 164   "portable_data_hash": "d41d8cd98f00b204e9800998ecf8427e+0",
 165   "manifest_text": "",
 166   "replication_desired": null,
 167   "replication_confirmed": null,
 168   "replication_confirmed_at": null,
 169   "expires_at": null
 170 }
 171 </pre>
 172
 173 h3. Get a specific record
 174
 175 <pre>
 176 $ curl -v -H "Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km | jq .
 177 > GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km HTTP/1.1
 178 > User-Agent: curl/7.38.0
 179 > Host: 192.168.5.2:8000
 180 > Accept: */*
 181 > Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
 182 >
 183 < HTTP/1.1 200 OK
 184 < Content-Type: application/json; charset=utf-8
 185 < Transfer-Encoding: chunked
 186 < Connection: keep-alive
 187 < Status: 200 OK
 188 < Access-Control-Allow-Origin: *
 189 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
 190 < Access-Control-Allow-Headers: Authorization
 191 < Access-Control-Max-Age: 86486400
 192 < X-UA-Compatible: IE=Edge,chrome=1
 193 < ETag: "fec2ddf433a352e5a2b5d356abd6d3d4"
 194 < Cache-Control: max-age=0, private, must-revalidate
 195 < X-Request-Id: 40b447507ff202ae9a0b0b3e0ebe98da
 196 < X-Runtime: 0.011404
 197 < X-Powered-By: Phusion Passenger 4.0.41
 198 < Date: Fri, 28 Oct 2016 18:59:09 GMT
 199 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
 200 <
 201 {
 202   "kind": "arvados#collection",
 203   "etag": "3mmn0s9e1z5s5opfofmtb9k8p",
 204   "uuid": "962eh-4zz18-xi32mpz2621o8km",
 205   "owner_uuid": "962eh-tpzed-000000000000000",
 206   "created_at": "2016-10-27T14:47:43.792587000Z",
 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: Bearer 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: Bearer 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       "kind": "arvados#collection",
 260       "etag": "bvgrrsg63zsenb9wnpnp0nsgl",
 261       "uuid": "962eh-4zz18-ybggo9im899vv60",
 262       "owner_uuid": "962eh-tpzed-000000000000000",
 263       "created_at": "2016-11-08T21:47:36.937106000Z",
 264       "modified_by_user_uuid": "962eh-tpzed-000000000000000",
 265       "modified_at": "2016-11-08T21:47:36.936625000Z",
 266       "name": "Log from cwl-runner job 962eh-8i9sb-45jww0k15fi5ldd",
 267       "description": null,
 268       "properties": {},
 269       "portable_data_hash": "a7820b94717eff86229927565fedbd72+85",
 270       "replication_desired": null,
 271       "replication_confirmed": null,
 272       "replication_confirmed_at": null,
 273       "expires_at": null
 274     },
 275    ...
 276     {
 277       "kind": "arvados#collection",
 278       "etag": "2fa07dx52lux8wa1loehwyrc5",
 279       "uuid": "962eh-4zz18-37i1tfl5de5ild9",
 280       "owner_uuid": "962eh-tpzed-000000000000000",
 281       "created_at": "2016-11-08T21:38:46.717798000Z",
 282       "modified_by_user_uuid": "962eh-tpzed-000000000000000",
 283       "modified_at": "2016-11-08T21:38:46.717409000Z",
 284       "name": null,
 285       "description": null,
 286       "properties": {},
 287       "portable_data_hash": "9d43d4c8328640446f6e252cda584e7e+54",
 288       "replication_desired": null,
 289       "replication_confirmed": null,
 290       "replication_confirmed_at": null,
 291       "expires_at": null
 292     }
 293   ],
 294   "items_available": 99
 295 }
 296 </pre>
 297
 298 h3. Update a field
 299
 300 <pre>
 301 $ 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 .
 302 > PUT /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km HTTP/1.1
 303 > User-Agent: curl/7.38.0
 304 > Host: 192.168.5.2:8000
 305 > Accept: */*
 306 > Authorization: Bearer oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr
 307 > Content-Length: 53
 308 > Content-Type: application/x-www-form-urlencoded
 309 >
 310 } [data not shown]
 311 < HTTP/1.1 200 OK
 312 < Content-Type: application/json; charset=utf-8
 313 < Transfer-Encoding: chunked
 314 < Connection: keep-alive
 315 < Status: 200 OK
 316 < Access-Control-Allow-Origin: *
 317 < Access-Control-Allow-Methods: GET, HEAD, PUT, POST, DELETE
 318 < Access-Control-Allow-Headers: Authorization
 319 < Access-Control-Max-Age: 86486400
 320 < X-UA-Compatible: IE=Edge,chrome=1
 321 < ETag: "fbb50d2847426eab793e3fcf346ca9eb"
 322 < Cache-Control: max-age=0, private, must-revalidate
 323 < Set-Cookie: _server_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFVEkiJWI3NjFjMzVjMGI5OGExYmNjZDg0ZTg5MjZhMzcwMDE1BjsAVA%3D%3D--0e005d71fad15cb366e47361c38474b7447ba155; path=/; HttpOnly
 324 < X-Request-Id: 76d3cb3c0995af6133b0a73a64f57354
 325 < X-Runtime: 0.030756
 326 < X-Powered-By: Phusion Passenger 4.0.41
 327 < Date: Fri, 28 Oct 2016 19:15:16 GMT
 328 < Server: nginx/1.4.7 + Phusion Passenger 4.0.41
 329 <
 330 {
 331   "kind": "arvados#collection",
 332   "etag": "51509hhxo9qqjxqewnoz1b7og",
 333   "uuid": "962eh-4zz18-xi32mpz2621o8km",
 334   "owner_uuid": "962eh-tpzed-000000000000000",
 335   "created_at": "2016-10-27T14:47:43.792587000Z",
 336   "modified_by_user_uuid": "962eh-tpzed-000000000000000",
 337   "modified_at": "2016-10-28T19:15:16.137814000Z",
 338   "name": "rna.SRR948778.bam",
 339   "description": null,
 340   "properties": {},
 341   "portable_data_hash": "93a45073511646a5c3e2f4953fcf6f61+116",
 342   "manifest_text": ". eff999f3b5158331eb44a9a93e3b36e1+67108864+Acca57af82cc18c5dfa47bdfd16e335fccd09dfa5@582618c4 db141bfd11f7da60dce9e5ee85a988b8+34038725+A7764f122f41f92c2d5bde1852fcdd1bea5f8bd78@582618c4 0:101147589:rna.SRR948778.bam\n",
 343   "replication_desired": null,
 344   "replication_confirmed": null,
 345   "replication_confirmed_at": null,
 346   "expires_at": null
 347 }
 348 </pre>