doc/api/methods/collections.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "collections"
   6
   7 ...
   8
   9 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/collections@
  10
  11 Object type: @4zz18@
  12
  13 Example UUID: @zzzzz-4zz18-0123456789abcde@
  14
  15 h2. Resource
  16
  17 Collections describe sets of files in terms of data blocks stored in Keep.  See "storage in Keep":{{site.baseurl}}/api/storage.html for details.
  18
  19 Each collection has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  20
  21 table(table table-bordered table-condensed).
  22 |_. Attribute|_. Type|_. Description|_. Example|
  23 |name|string|||
  24 |description|text|||
  25 |portable_data_hash|string|The MD5 sum of the manifest text stripped of block hints other than the size hint.||
  26 |manifest_text|text|||
  27 |replication_desired|number|Minimum storage replication level desired for each data block referenced by this collection. A value of @null@ signifies that the site default replication level (typically 2) is desired.|@2@|
  28 |replication_confirmed|number|Replication level most recently confirmed by the storage system. This field is null when a collection is first created, and is reset to null when the manifest_text changes in a way that introduces a new data block. An integer value indicates the replication level of the _least replicated_ data block in the collection.|@2@, null|
  29 |replication_confirmed_at|datetime|When replication_confirmed was confirmed. If replication_confirmed is null, this field is also null.||
  30
  31 h3. Conditions of creating a Collection
  32
  33 The @portable_data_hash@ and @manifest_text@ attributes must be provided when creating a Collection. The cryptographic digest of the supplied @manifest_text@ must match the supplied @portable_data_hash@.
  34
  35 h3. Side effects of creating a Collection
  36
  37 Referenced blocks are protected from garbage collection in Keep.
  38
  39 Data can be shared with other users via the Arvados permission model.
  40
  41 h2. Methods
  42
  43 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  44
  45 Required arguments are displayed in %{background:#ccffcc}green%.
  46
  47 h3. create
  48
  49 Create a new Collection.
  50
  51 Arguments:
  52
  53 table(table table-bordered table-condensed).
  54 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  55 |collection|object||query||
  56
  57 h3. delete
  58
  59 Delete an existing Collection.
  60
  61 Arguments:
  62
  63 table(table table-bordered table-condensed).
  64 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  65 {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path||
  66
  67 h3. get
  68
  69 Gets a Collection's metadata by UUID.
  70
  71 Arguments:
  72
  73 table(table table-bordered table-condensed).
  74 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  75 {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path||
  76
  77 h3. list
  78
  79 List collections.
  80
  81 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
  82
  83 Note: Because adding access tokens to manifests can be computationally expensive, the @manifest_text@ field is not included in results by default.  If you need it, pass a @select@ parameter that includes @manifest_text@.
  84
  85 h3. update
  86
  87 Update attributes of an existing Collection.
  88
  89 Arguments:
  90
  91 table(table table-bordered table-condensed).
  92 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  93 {background:#ccffcc}.|uuid|string|The UUID of the Collection in question.|path||
  94 |collection|object||query||