...
-(using Group as an example)
+The following methods are available for most resources. Some resources may limit who can perform certain operations. Consult documentation for individual resource types for details.
-h2(#index). Index, list, search
+h2. create
-<pre>
-GET https://{{ site.arvados_api_host }}/arvados/v1/groups?filters=[["owner_uuid","=","xyzzy-tpzed-a4lcehql0dv2u25"]]
+The @create@ method creates a new object of the specified type. It corresponds to the HTTP request @POST /arvados/v1/resource_name@. A successful create call returns a copy of the new object.
-POST https://{{ site.arvados_api_host }}/arvados/v1/groups
-_method=GET
-filters=[["owner_uuid","=","xyzzy-tpzed-a4lcehql0dv2u25"]]
-</pre>
+Arguments:
-→ Group resource list
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |
+|{resource_name}|object||query||
+
+h2. delete
+
+The @delete@ method deletes a object of the specified type. It corresponds to the HTTP request @DELETE /arvados/v1/resource_name/uuid@. A successful delete call returns a copy of the deleted object.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |
+{background:#ccffcc}.|uuid|string|The UUID of the object in question.|path|
+
+h2. get
+
+The @get@ method gets a single object with the specified @uuid@. It corresponds to the HTTP request @GET /arvados/v1/resource_name/uuid@.
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |
+{background:#ccffcc}.|uuid|string|The UUID of the object in question.|path|
+
+h2(#index). list
+
+The @list@ method requests an list of resources of that type. It corresponds to the HTTP request @GET /arvados/v1/resource_name@. All resources support listing with unless otherwise noted.
+
+Arguments:
table(table table-bordered table-condensed).
-|*Parameter name*|*Value*|*Description*|
-|limit |integer|Maximum number of resources to return.|
-|offset |integer|Skip the first 'offset' resources that match the given filter conditions.|
-|filters |array |Conditions for selecting resources to return (see below).|
+|_. Argument |_. Type |_. Description |_. Location |
+|limit |integer|Maximum number of resources to return. May also be subject to server limit.|query|
+|offset |integer|Skip the first 'offset' resources that match the given filter conditions.|query|
+|filters |array |Conditions for selecting resources to return (see below).|query|
|order |array |Attributes to use as sort keys to determine the order resources are returned, each optionally followed by @asc@ or @desc@ to indicate ascending or descending order.
Example: @["head_uuid asc","modified_at desc"]@
-Default: @["created_at desc"]@|
+Default: @["created_at desc"]@|query|
|select |array |Set of attributes to include in the response.
Example: @["head_uuid","tail_uuid"]@
-Default: all available attributes, minus "manifest_text" in the case of collections.|
+Default: all available attributes. As a special case, collections do not return "manifest_text" unless explicitly selected.|query|
|distinct|boolean|@true@: (default) do not return duplicate objects
-@false@: permitted to return duplicates|
+@false@: permitted to return duplicates|query|
-h3. Filters
+h3. filters
The value of the @filters@ parameter is an array of conditions. The @list@ method returns only the resources that satisfy all of the given conditions. In other words, the conjunction @AND@ is implicit.
|@in@, @not in@|array of strings|@["script_version","in",["master","d00220fb38d4b85ca8fc28a8151702a2b9d1dec5"]]@|
|@is_a@|string|@["head_uuid","is_a","arvados#pipelineInstance"]@|
-h2. Create
-
-<pre>
-POST https://{{ site.arvados_api_host }}/arvados/v1/groups
-group={"name":"fresh new group"}
-</pre>
-
-→ Group resource
-
-h2. Delete
-
-<pre>
-DELETE https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg
-</pre>
+h3. result
-→ Group resource
+A successful call to list will return the following object.
-h2. Update
-
-<pre>
-PUT https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg
-group={"uuid":"xyzzy-ldvyl-vyydjeplwaa6emg", "name":"Important group"}
-</pre>
-
-→ Group resource
-
-<pre>
-PUT https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg
-group[uuid]=xyzzy-ldvyl-vyydjeplwaa6emg
-group[name]=Important group
-</pre>
-
-→ Group resource
+table(table table-bordered table-condensed).
+|_. Attribute |_. Type |_. Description |
+|kind|string|type of objects returned|
+|offset|integer|query offset in effect|
+|limit|integer|query limit in effect|
+|items|array|actual query payload, an array of resource objects|
+|items_available|integer|total items available matching query|
-More appropriate (but not yet implemented):
+h2. update
-<pre>
-PATCH https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg
-group={"uuid":"xyzzy-ldvyl-vyydjeplwaa6emg", "name":"Important group"}
-</pre>
+The @update@ method updates fields on the object with the specified @uuid@. It corresponds to the HTTP request @PUT /arvados/v1/resource_name/uuid@. A successful update call returns the updated copy of the object.
-→ Group resource
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |
+{background:#ccffcc}.|uuid|string|The UUID of the resource in question.|path||
+|{resource_name}|object||query||
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.
+h3. Result
+
+Results are returned JSON-encoded in the response body.
+
+h3. Errors
+
+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:
+
+table(table table-bordered table-condensed).
+|*Parameter name*|*Value*|*Description*|
+|errors|array|An array of one or more error messages|
+|error_token|string|a unique identifier used to correlate the error in the API server logs|
+
h2. Examples
-h3. Get a specific collection
+h3. Get a specific record
<pre>
$ curl -v -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km | jq .
}
</pre>
-h3. List collections and filter by uuid
+h3. List records and filter by uuid
<pre>
$ curl -v -G --data-urlencode 'filters=[["uuid", "=", "962eh-4zz18-xi32mpz2621o8km"]]' -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections | jq .
h3. Delete a record
+<pre>
$ curl -X DELETE -v -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" https://192.168.5.2:8000/arvados/v1/collections/962eh-4zz18-m1ma0mxxfg3mbcc | jq .
> DELETE /arvados/v1/collections/962eh-4zz18-m1ma0mxxfg3mbcc HTTP/1.1
> User-Agent: curl/7.38.0
"replication_confirmed_at": null,
"expires_at": null
}
+</pre>
...
-
-
This page describes the common attributes of Arvados resources.
-The list of resource types is on the "front page of the API Reference":./.
-
-h2. Object IDs
-
-Object IDs are alphanumeric strings, unique across all installations (each installation has a unique prefix to prevent collisions).
-
-h2(#resource). Attributes of resources
+h2(#resource). Resource
table(table table-bordered table-condensed).
-|*Attribute*|*Type*|*Description*|*Example*|
+|_. Attribute |_. Type |_. Description |_. Example|
|uuid|string|universally unique object identifier|@mk2qn-4zz18-w3anr2hk2wgfpuo@|
|href|string|a URL that can be used to address this resource||
|kind|string|@arvados#{resource_type}@|@arvados#collection@|
|etag|string|The ETag[1] of the resource|@1xlmizzjq7wro3dlb2dirf505@|
-|self_link|string|||
-|owner_uuid|string|UUID of owner (typically User or Project)|@mk2qn-tpzed-a4lcehql0dv2u25@|
+|owner_uuid|string|UUID of owner (must be a User or Group)|@mk2qn-tpzed-a4lcehql0dv2u25@|
|created_at|datetime|When resource was created|@2013-01-21T22:17:39Z@|
|modified_by_client_uuid|string|API client software which most recently modified the resource|@mk2qn-ozdt8-vq8l5qkzj7pr7h7@|
|modified_by_user_uuid|string|Authenticated user, on whose behalf the client was acting when modifying the resource|@mk2qn-tpzed-a4lcehql0dv2u25@|
|modified_at|datetime|When resource was last modified|@2013-01-25T22:29:32Z@|
-h2(#resourceList). Attributes of resource lists
+h2. Object UUID
-table(table table-bordered table-condensed).
-|*Attribute*|*Type*|*Description*|*Example*|
-|kind|string|@arvados#{resource_type}List@|@arvados#projectList@|
-|etag|string|The ETag[1] of the resource list|@cd3o1wi9sf934saajykawrz2e@|
-|self_link|string|||
-|next_page_token|string|||
-|next_link|string|||
-|items[]|list|List of resources||
+Each object is assigned a UUID. This has the format @aaaaa-bbbbb-ccccccccccccccc@.
+format.
+
+# The first field ("aaaaa" in the example) is the site prefix. This is unique to a specific Arvados installation.
+# The second field ("bbbbb" in the example) is the object type.
+# The third field ("ccccccccccccccc" in the example) uniquely identifies the object.
+
+h2. Timestamps
+All Arvados timestamps follow ISO 8601 datetime format with fractional seconds (microsecond precision). All timestamps are UTC. Example date format: @YYYY-mm-ddTHH:MM:SS.SSSSZ@
h2. ETags
projects / arvados.git / commitdiff