3354: Merge branch 'master' into 3354-render-textile
[arvados.git] / doc / api / methods.html.textile.liquid
1 ---
2 layout: default
3 navsection: api
4 navmenu: Concepts
5 title: REST methods
6
7 ...
8
9
10
11 (using Group as an example)
12
13 h2(#index). Index, list, search
14
15 <pre>
16 GET https://{{ site.arvados_api_host }}/arvados/v1/groups?filters=[["owner_uuid","=","xyzzy-tpzed-a4lcehql0dv2u25"]]
17
18 POST https://{{ site.arvados_api_host }}/arvados/v1/groups
19 _method=GET
20 filters=[["owner_uuid","=","xyzzy-tpzed-a4lcehql0dv2u25"]]
21 </pre>
22
23 &rarr; Group resource list
24
25 table(table table-bordered table-condensed).
26 |*Parameter name*|*Value*|*Description*|
27 |limit   |integer|Maximum number of resources to return.|
28 |offset  |integer|Skip the first 'offset' resources that match the given filter conditions.|
29 |filters |array  |Conditions for selecting resources to return (see below).|
30 |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.
31 Example: @["head_uuid asc","modified_at desc"]@
32 Default: @["created_at desc"]@|
33 |select  |array  |Set of attributes to include in the response.
34 Example: @["head_uuid","tail_uuid"]@
35 Default: all available attributes, minus "manifest_text" in the case of collections.|
36 |distinct|boolean|@true@: (default) do not return duplicate objects
37 @false@: permitted to return duplicates|
38
39 h3. Filters
40
41 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.
42
43 Each condition is expressed as an array with three elements: @[attribute, operator, operand]@.
44
45 table(table table-bordered table-condensed).
46 |_. Index|_. Element|_. Type|_. Description|_. Examples|
47 |0|attribute|string|Name of the attribute to compare (or "any" to return resources with any matching attribute)|@script_version@, @head_uuid@, @any@|
48 |1|operator|string|Comparison operator|@>@, @>=@, @like@, @not in@|
49 |2|operand|string, array, or null|Value to compare with the resource attribute|@"d00220fb%"@, @"1234"@, @["foo","bar"]@, @nil@|
50
51 The following operators are available.
52
53 table(table table-bordered table-condensed).
54 |_. Operator|_. Operand type|_. Example|
55 |@<@, @<=@, @>=@, @>@, @like@, @ilike@|string|@["script_version","like","d00220fb%"]@|
56 |@=@, @!=@|string or null|@["tail_uuid","=","xyzzy-j7d0g-fffffffffffffff"]@
57 @["tail_uuid","!=",null]@|
58 |@in@, @not in@|array of strings|@["script_version","in",["master","d00220fb38d4b85ca8fc28a8151702a2b9d1dec5"]]@|
59 |@is_a@|string|@["head_uuid","is_a","arvados#pipelineInstance"]@|
60
61 h2. Create
62
63 <pre>
64 POST https://{{ site.arvados_api_host }}/arvados/v1/groups
65 group={"name":"fresh new group"}
66 </pre>
67
68 &rarr; Group resource
69
70 h2. Delete
71
72 <pre>
73 DELETE https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg
74 </pre>
75
76 &rarr; Group resource
77
78 h2. Update
79
80 <pre>
81 PUT https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg
82 group={"uuid":"xyzzy-ldvyl-vyydjeplwaa6emg", "name":"Important group"}
83 </pre>
84
85 &rarr; Group resource
86
87 <pre>
88 PUT https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg
89 group[uuid]=xyzzy-ldvyl-vyydjeplwaa6emg
90 group[name]=Important group
91 </pre>
92
93 &rarr; Group resource
94
95 More appropriate (but not yet implemented):
96
97 <pre>
98 PATCH https://{{ site.arvados_api_host }}/arvados/v1/groups/xyzzy-ldvyl-vyydjeplwaa6emg
99 group={"uuid":"xyzzy-ldvyl-vyydjeplwaa6emg", "name":"Important group"}
100 </pre>
101
102 &rarr; Group resource