Common resource methods

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.

The methods are relative to the base URI, e.g., /arvados/v1/resource_type. For arguments specifying a Location of path, the value of the argument is incorporated into the path portion of the URI. For example, a uuid of aaaaa-bbbbb-ccccccccccccccc in a path position yields a URI of /arvados/v1/resource_type/aaaaa-bbbbb-ccccccccccccccc.

Arguments specifying a Location of query are incorporated into the query portion of the URI or request body. For example, /arvados/v1/resource_type?resource_type={}.

create

The create method creates a new object of the specified type. Note that:

  • Only the listed attributes (and standard metadata) are set
  • Unset attributes will get default values
  • The attributes of a given resource type are fixed (you cannot introduce new toplevel attributes)

This method corresponds to the HTTP request POST /arvados/v1/resource_type. A successful create call returns a copy of the new object.

Arguments:

Argument Type Description Location
{resource_type} object Name is the singular form of the resource type, e.g., for the “collections” resource, this argument is “collection” query

delete

The delete method deletes an object of the specified type. It corresponds to the HTTP request DELETE /arvados/v1/resource_type/uuid. A successful delete call returns a copy of the deleted object.

Arguments:

Argument Type Description Location
uuid string The UUID of the object in question. path

get

The get method gets a single object with the specified uuid. It corresponds to the HTTP request GET /arvados/v1/resource_type/uuid.

Arguments:

Argument Type Description Location
uuid string The UUID of the object in question. path

list

The list method requests an list of resources of that type. It corresponds to the HTTP request GET /arvados/v1/resource_type. All resources support “list” method unless otherwise noted.

Arguments:

Argument Type Description Location
limit integer Maximum number of resources to return. If not provided, server will provide a default limit. Server may also impose a maximum number of records that can be returned in a single request. query
offset integer Skip the first ‘offset’ number of resources that would be returned under the given filter conditions. query
filters array Conditions for selecting resources to return. 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"]
query
select array Set of attributes to include in the response.
Example: ["head_uuid","tail_uuid"]
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
query
count string "exact" (default): Include an items_available response field giving the number of distinct matching items that can be retrieved (irrespective of limit and offset arguments).
"none": Omit the items_available response field. This option will produce a faster response.
query

Available list method 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.

Each condition is expressed as an array with three elements: [attribute, operator, operand].

Index Element Type Description Examples
0 attribute string Name of the attribute to compare (or “any” to return resources with any matching attribute) script_version, head_uuid, any
1 operator string Comparison operator >, >=, like, not in
2 operand string, array, or null Value to compare with the resource attribute "d00220fb%", "1234", ["foo","bar"], nil

The following operators are available.

Operator Operand type Example
<, <=, >=, >, like, ilike string ["script_version","like","d00220fb%"]
=, != string or null ["tail_uuid","=","xyzzy-j7d0g-fffffffffffffff"]
["tail_uuid","!=",null]
in, not in array of strings ["script_version","in",["master","d00220fb38d4b85ca8fc28a8151702a2b9d1dec5"]]
is_a string ["head_uuid","is_a","arvados#pipelineInstance"]

Results of list method

A successful call to list will return the following object.

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

update

The update method updates fields on the object with the specified uuid. It corresponds to the HTTP request PUT /arvados/v1/resource_type/uuid. Note that only the listed attributes (and standard metadata) are updated, unset attributes will retain their previous values, and the attributes of a given resource type are fixed (you cannot introduce new toplevel attributes). Also note that updates replace the value of the attribute, so if an attribute has an object value, the entire object is replaced. A successful update call returns the updated copy of the object.

Argument Type Description Location
uuid string The UUID of the resource in question. path
{resource_type} object query

Previous: REST API syntax Next: Common resource fields

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.