doc/api/methods.html.textile.liquid

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