X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/a7f378b2267ddc1b44a8661d6723264fe959d98e..98d6c8c5743e0fd6be85af3b9f30286a358bd1d4:/doc/api/methods.html.textile.liquid diff --git a/doc/api/methods.html.textile.liquid b/doc/api/methods.html.textile.liquid index 0110ebbcd7..00c120d9f8 100644 --- a/doc/api/methods.html.textile.liquid +++ b/doc/api/methods.html.textile.liquid @@ -2,79 +2,133 @@ layout: default navsection: api navmenu: Concepts -title: REST methods +title: Common resource methods ... +{% comment %} +Copyright (C) The Arvados Authors. All rights reserved. +SPDX-License-Identifier: CC-BY-SA-3.0 +{% endcomment %} +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. -(using Group as an example) +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@. -h2(#index). Index, list, search +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={}@. -
-GET https://{{ site.arvados_api_host }}/arvados/v1/groups?where[owner_uuid]=xyzzy-tpzed-a4lcehql0dv2u25 - -POST https://{{ site.arvados_api_host }}/arvados/v1/groups -_method=GET -where[owner_uuid]=xyzzy-tpzed-a4lcehql0dv2u25 -+h2. create -→ Group resource list +The @create@ method creates a new object of the specified type. Note that: + +* Only the listed attributes (and "standard metadata":resources.html) 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: table(table table-bordered table-condensed). -|*Parameter name*|*Value*|*Description*| -|max_results|integer|Maximum number of resources to return| -|page_token|string|| -|where{}|list|Attribute values to search for| +|_. 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|| -h2. Create +h2. delete -
-POST https://{{ site.arvados_api_host }}/arvados/v1/groups -group={"name":"fresh new group"} -+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. -→ Group resource +Arguments: + +table(table table-bordered table-condensed). +|_. Argument |_. Type |_. Description |_. Location | +{background:#ccffcc}.|uuid|string|The UUID of the object in question.|path| -h2. Delete +h2. get -
-DELETE https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg -+The @get@ method gets a single object with the specified @uuid@. It corresponds to the HTTP request @GET /arvados/v1/resource_type/uuid@. -→ Group resource +Arguments: -h2. Show +table(table table-bordered table-condensed). +|_. Argument |_. Type |_. Description |_. Location | +{background:#ccffcc}.|uuid|string|The UUID of the object in question.|path| -
-GET https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg -+h2(#index). list -→ Group resource +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. -h2. Update +Arguments: -
-PUT https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg -group={"uuid":"xyzzy-ldvyl-vyydjeplwaa6emg", "name":"Important group"} -+table(table table-bordered table-condensed). +|_. 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.":#filters|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| + +h3(#filters). 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]@. -→ Group resource +table(table table-bordered table-condensed). +|_. 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@| -
-PUT https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg -group[uuid]=xyzzy-ldvyl-vyydjeplwaa6emg -group[name]=Important group -+The following operators are available. -→ Group resource +table(table table-bordered table-condensed). +|_. 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"]@| -More appropriate (but not yet implemented): +h4. Filtering on subproperties -
-PATCH https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg -group={"uuid":"xyzzy-ldvyl-vyydjeplwaa6emg", "name":"Important group"} -+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.