X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/11c6f1d759040f2af8a68d80ae78dd57a9b2d976..45ebdd1005f12c3c18355ab511e7a2e7f623358a:/doc/api/methods.html.textile.liquid diff --git a/doc/api/methods.html.textile.liquid b/doc/api/methods.html.textile.liquid index 57d058e157..7b28533e30 100644 --- a/doc/api/methods.html.textile.liquid +++ b/doc/api/methods.html.textile.liquid @@ -2,74 +2,195 @@ 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?count=none@. -
-GET https://{{ site.arvados_api_host }}/arvados/v1/groups?filters=[["owner_uuid","=","xyzzy-tpzed-a4lcehql0dv2u25"]] +Certain method calls on certain object types support "federation":{{site.baseurl}}/architecture/federation.html , that is, the ability to operate on objects owned by different clusters. API pages for specific object types list which federated operations are supported for that type (if any) in the "Methods" section. Methods which implicitly include a cluster id (such as @GET@ on a specific uuid, using the uuid prefix) will be directed to the appropriate cluster. Methods that don't implicitly include the cluster id (such as @create@) use the @cluster_id@ query parameter to specify which cluster to direct the request. -POST https://{{ site.arvados_api_host }}/arvados/v1/groups -_method=GET -filters=[["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. + +To create an object on a remote cluster (federated create), provide the @cluster_id@ of the target cluster. + +Arguments: + +table(table table-bordered table-condensed). +|_. 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"|body| +|{cluster_id}|string|Optional, the cluster on which to create the object if not the current cluster.|query| +|select |array |Attributes of the new object to return in the response (by default, all available attributes are returned). +Example: @["uuid","name","modified_at"]@|query| + +h2. 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. + +The cluster id portion of the @uuid@ is used to determine which cluster owns the object, a federated delete request will be routed to that cluster. + +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' objects| -|filters |array |Conditions for selecting resources to return| -|order |array |List of fields to use to determine sorting order for returned objects| -|select |array |Specify which fields to return| -|distinct|boolean|true: (default) do not return duplicate objects
-POST https://{{ site.arvados_api_host }}/arvados/v1/groups -group={"name":"fresh new group"} -+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 +The cluster id portion of the @uuid@ is used to determine which cluster owns the object, a federated get request will be routed to that cluster. -h2. Delete +Arguments: -
-DELETE https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg -+table(table table-bordered table-condensed). +|_. Argument |_. Type |_. Description |_. Location | +{background:#ccffcc}.|uuid|string|The UUID of the object in question.|path| +|select |array |Attributes of the object to return in the response (by default, all available attributes are returned). +Example: @["uuid","name","modified_at"]@|query| + +h2(#index). 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 the @list@ method unless otherwise noted. + +Arguments: + +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. (If not specified, it will be ascending). +Example: @["head_uuid asc","modified_at desc"]@ +Default: @["modified_at desc", "uuid asc"]@|query| +|select |array |Attributes of each object to return in the response (by default, all available attributes are returned, except collections, which do not return @manifest_text@ unless explicitly selected). +Example: @["uuid","name","modified_at"]@|query| +|distinct|boolean|When returning multiple records whose selected attributes (see @select@) are equal, return them as a single response entry. +Default is @false@.|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@| -h2. Update +The following operators are available. -
-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). +|_. Operator|_. Operand type|_. Description|_. Example| +|@=@, @!=@, @<>@|string, number, timestamp, JSON-encoded array, JSON-encoded object, or null|Equality comparison|@["tail_uuid","=","xyzzy-j7d0g-fffffffffffffff"]@ +@["tail_uuid","!=",null]@ +@["storage_classes_desired","=","[\"default\"]"]@| +|@<@, @<=@, @>=@, @>@|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 or integers|Set membership|@["script_version","in",["main","d00220fb38d4b85ca8fc28a8151702a2b9d1dec5"]]@| +|@is_a@|string|Arvados object type|@["head_uuid","is_a","arvados#collection"]@| +|@exists@|string|Presence of subproperty|@["properties","exists","my_subproperty"]@| +|@contains@|string, array of strings|Presence of one or more keys or array elements|@["storage_classes_desired", "contains", ["foo", "bar"]]@ (matches both @["foo", "bar"]@ and @["foo", "bar", "baz"]@) +(note @[..., "contains", "foo"]@ is also accepted, and is equivalent to @[..., "contains", ["foo"]]@)| -→ Group resource +h4(#substringsearchfilter). Filtering using substring search -
-PUT https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg -group[uuid]=xyzzy-ldvyl-vyydjeplwaa6emg -group[name]=Important group -+Resources can also be filtered by searching for a substring in attributes of type @string@, @array of strings@, @text@, and @hash@, which are indexed in the database specifically for search. To use substring search, the filter must: -→ Group resource +* Specify @any@ as the attribute +* Use either the @like@ or @ilike@ operator +* Have an operand of type @string@ that is wrapped in the SQL pattern match wildcard character @%@ -More appropriate (but not yet implemented): +For example, the @["any", "like", "%foo%"]@ filter will return all resources that contain @foo@ in the content of at least one attribute of the previously defined types. This is the recommended way to do keyword and file name search across the entire database. Note that only exact substring matches are returned and results are unranked and returned in the order specified by the @list@ @order@ argument. -
-PATCH https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg -group={"uuid":"xyzzy-ldvyl-vyydjeplwaa6emg", "name":"Important group"} -+h4(#subpropertyfilters). Filtering on subproperties -→ Group resource +Some record types 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.