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	Description	Example
=, !=	string, number, timestamp, or null	Equality comparison	["tail_uuid","=","xyzzy-j7d0g-fffffffffffffff"] ["tail_uuid","!=",null]
<, <=, >=, >	string, number, or timestamp	Ordering comparison	["script_version",">","123"]
like, ilike	string	SQL pattern match. Single character match is _ and wildcard is %. The ilike operator is case-insensitive	["script_version","like","d00220fb%"]
in, not in	array of strings	Set membership	["script_version","in",["master","d00220fb38d4b85ca8fc28a8151702a2b9d1dec5"]]
is_a	string	Arvados object type	["head_uuid","is_a","arvados#collection"]
exists	string	Test if a subproperty is present.	["properties","exists","my_subproperty"]

Filtering on subproperties

Some record type have an additional properties attribute that allows recording and filtering on additional key-value pairs. To filter on a subproperty, the value in the attribute position has the form properties.user_property. You may also use JSON-LD / RDF style URIs for property keys by enclosing them in <...> for example properties.<http://example.com/user_property>. Alternately you may also provide a JSON-LD “@context” field, however at this time JSON-LD contexts are not interpreted by Arvados.

Operator	Operand type	Description	Example
=, !=	string, number or boolean	Equality comparison	["properties.my_subproperty", "=", "fizzy whizy sparkle pop"]
<, <=, >=, >	string or number	Ordering comparison	["properties.my_subproperty", "<", 3]
like, ilike	string	SQL pattern match, single character match is _ and wildcard is %, ilike is case-insensitive	["properties.my_subproperty", "like", "d00220fb%"]
in, not in	array of strings	Set membership	["properties.my_subproperty", "in", ["fizz", "buzz"]]
exists	boolean	Test if a subproperty is present or not (determined by operand).	["properties.my_subproperty", "exists", true]

Note that exclusion filters != and not in will return records for which the property is not defined at all. To restrict filtering to records on which the subproperty is defined, combine with an exists filter.

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