doc/api/requests.html.textile.liquid

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