doc/api/requests.html.textile.liquid

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