10346: Added UUID type to each resource. Some formatting cleanups.

diff --git a/doc/_config.yml b/doc/_config.yml
index 4f9e200ca954c4f7aa4ba969c659ce5e5b669a4c..2f66fcd6c1129f9ff420b1463e63e88d9050896c 100644 (file)
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -109,11 +109,11 @@ navbar:
       - api/permission-model.html.textile.liquid
       - api/execution.html.textile.liquid
     - Permission and authentication:
-      - api/methods/users.html.textile.liquid
-      - api/methods/groups.html.textile.liquid
       - api/methods/api_client_authorizations.html.textile.liquid
       - api/methods/api_clients.html.textile.liquid
       - api/methods/authorized_keys.html.textile.liquid
+      - api/methods/groups.html.textile.liquid
+      - api/methods/users.html.textile.liquid
     - System resources:
       - api/methods/keep_services.html.textile.liquid
       - api/methods/links.html.textile.liquid

diff --git a/doc/api/execution.html.textile.liquid b/doc/api/execution.html.textile.liquid
new file mode 100644 (file)
index 0000000..ade3f5c
--- /dev/null
+++ b/doc/api/execution.html.textile.liquid
@@ -0,0 +1,25 @@
+---
+layout: default
+navsection: api
+title: Computing with Crunch
+...
+
+Crunch is the name for the Arvados system for managing computation.  It provides an abstract API to various clouds and HPC resource allocation and scheduling systems.
+
+h2. Container API
+
+Note: although the preferred API for Aravdos going forward, the Container API may not yet be available on all installations.
+
+# To submit work, create a "container request":{{site.baseurl}}/api/methods/container_requests.html in the @Committed@ state.
+# The system will fufill the container request by creating a "Container object":{{site.baseurl}}/api/methods/containers.html or, if the same request has been submitted in the past, reusing an existing container.  This will be assigned to the @container_uuid@ field.
+# The dispatcher process will notice a new container in @Queued@ state and submit a container executor to the underyling work queuing system (such as SLURM).
+# The container executes.  Upon termination the container goes into the  @Complete@ state.  If the container execution was interrupted or lost due to system failure, it will go into the @Cancelled@ state.
+# When the container associated with the container request is completed, the container request will go into the @Final@ state.
+# Retrieve the container object; the @output@ field contains the portable data hash of collection with the output files of the container.
+
+h2. Job API (deprecated)
+
+# To submit work, create a "job":{{site.baseurl}}/api/methods/job.html .  If the same job has been submitted in the past, it will return an existing job in @Completed@ state.
+# The dispatcher process will notice a new job in @Queued@ state and attempt to allocate nodes to run the job.
+# The job executes.
+# Retrieve the @output@ field with the portable data hash of the collection with the output files of the job.

diff --git a/doc/api/methods/api_clients.html.textile.liquid b/doc/api/methods/api_clients.html.textile.liquid
index fa4d9d23fe33deacb8f985f18d408ca4d7a35ff1..3c668bdc5665a63591373a65e30d1db30f37270a 100644 (file)
--- a/doc/api/methods/api_clients.html.textile.liquid
+++ b/doc/api/methods/api_clients.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/api_clients@
 
+UUID type: @ozdt8@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/authorized_keys.html.textile.liquid b/doc/api/methods/authorized_keys.html.textile.liquid
index 62072ac84fd525e806d19170d6e077c500d22152..079d1500f689228074911a270af05a83f52eb25d 100644 (file)
--- a/doc/api/methods/authorized_keys.html.textile.liquid
+++ b/doc/api/methods/authorized_keys.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/authorized_keys@
 
+UUID type: @fngyi@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/collections.html.textile.liquid b/doc/api/methods/collections.html.textile.liquid
index 5662b3145f4cf9d8f03816b1a5cc0fdeee771705..563e20e7e2cb9221912a51412526ef39d2af679c 100644 (file)
--- a/doc/api/methods/collections.html.textile.liquid
+++ b/doc/api/methods/collections.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/collections@
 
+UUID type: @4zz18@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Methods

diff --git a/doc/api/methods/container_requests.html.textile.liquid b/doc/api/methods/container_requests.html.textile.liquid
index 2f7eac300f25586a56fbf28b2202032880a49037..a024527309c909168903c5c8a070e6198c7e98b5 100644 (file)
--- a/doc/api/methods/container_requests.html.textile.liquid
+++ b/doc/api/methods/container_requests.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/container_requests@
 
+UUID type: @xvhdp@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/containers.html.textile.liquid b/doc/api/methods/containers.html.textile.liquid
index 0ef1cf9fc692e45d585c14731a28485cec40d874..145b1d69ead61a1e679bd0885939f4511732edcb 100644 (file)
--- a/doc/api/methods/containers.html.textile.liquid
+++ b/doc/api/methods/containers.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/containers@
 
+UUID type: @dz642@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/groups.html.textile.liquid b/doc/api/methods/groups.html.textile.liquid
index b22926671aae241a034697da8a7d558be64c9099..3e4a2524bc1d15e89a7e1e010b501463161c0fcb 100644 (file)
--- a/doc/api/methods/groups.html.textile.liquid
+++ b/doc/api/methods/groups.html.textile.liquid
@@ -11,6 +11,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/groups@
 
+UUID type: @j7d0g@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/humans.html.textile.liquid b/doc/api/methods/humans.html.textile.liquid
index 207793843ad47788be4dd554fa4a51cb921a2c48..0d4b2ccd1ae09b90895ef6a820e102c6b78703bf 100644 (file)
--- a/doc/api/methods/humans.html.textile.liquid
+++ b/doc/api/methods/humans.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/humans@
 
+UUID type: @7a9it@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/job_tasks.html.textile.liquid b/doc/api/methods/job_tasks.html.textile.liquid
index a343d5449d5dea468f9eaed337d003cab8d1312e..6d031c9b3bcfe85a17ecc4863f4465acec639e6a 100644 (file)
--- a/doc/api/methods/job_tasks.html.textile.liquid
+++ b/doc/api/methods/job_tasks.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/job_tasks@
 
+UUID type: @ot0gb@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/jobs.html.textile.liquid b/doc/api/methods/jobs.html.textile.liquid
index 0c93eb69e4c566f19e1a3f0b3f33194ef88bb418..4779fb9762077f49a5ddbe0d685d3e85a67060de 100644 (file)
--- a/doc/api/methods/jobs.html.textile.liquid
+++ b/doc/api/methods/jobs.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/jobs@
 
+UUID type: @8i9sb@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/keep_disks.html.textile.liquid b/doc/api/methods/keep_disks.html.textile.liquid
index 37c7b145eea71d93461051c06cbc9f8d97c4ec24..7cec243ee4ecfc3cd736df0b92ee7a6c4bc7e10e 100644 (file)
--- a/doc/api/methods/keep_disks.html.textile.liquid
+++ b/doc/api/methods/keep_disks.html.textile.liquid
@@ -10,8 +10,12 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/keep_disks@
 
+UUID type: @penuu@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
+Obsoleted by "keep_services":{{site.baseurl}}/api/methods/keep_services.html
+
 h2. Resource
 
 Each KeepDisk has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
@@ -31,6 +35,7 @@ table(table table-bordered table-condensed).
 |keep_service_uuid|string|||
 
 h2. Methods
+
 h3. create
 
 Create a new KeepDisk.

diff --git a/doc/api/methods/keep_services.html.textile.liquid b/doc/api/methods/keep_services.html.textile.liquid
index 5fa8817ede69bce116063487ce61fedce5aeb443..97ed7d85805f21225e28a2e5137689fb910cf2af 100644 (file)
--- a/doc/api/methods/keep_services.html.textile.liquid
+++ b/doc/api/methods/keep_services.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/keep_services@
 
+UUID type: @bi6l4@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource
@@ -27,12 +29,10 @@ h2. Methods
 
 h3. accessible
 
-Get a list of keep services that are accessible to the requesting client.  This
-is context-sensitive, for example providing the list of actual Keep servers
-when inside the cluster, but providing a proxy service if client contacts
-Arvados from outside the cluster.
+Get a list of keep services that are accessible to the requesting client.  Unlike @list@, this is context-sensitive based on the requester, for example providing the list of actual Keep servers when inside the cluster, but providing a proxy service if client contacts Arvados from outside the cluster.
 
-Takes no arguments.
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
 
 h3. create
 

diff --git a/doc/api/methods/links.html.textile.liquid b/doc/api/methods/links.html.textile.liquid
index 003456c542e8ce7089cd2f27cb8b1ede9c06bdc6..99205bead3d9b6b88c1133fc3db635a1dfcbf473 100644 (file)
--- a/doc/api/methods/links.html.textile.liquid
+++ b/doc/api/methods/links.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/links@
 
+UUID type: @o0j2j@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource
@@ -79,6 +81,7 @@ table(table table-bordered table-condensed).
 
 
 h2. Methods
+
 h3. create
 
 Create a new Link.

diff --git a/doc/api/methods/logs.html.textile.liquid b/doc/api/methods/logs.html.textile.liquid
index 58ce979a289068b1ab4197d3a81fa7800d7ac7e1..e87807103604d5f760870856002e4ceff584bdcf 100644 (file)
--- a/doc/api/methods/logs.html.textile.liquid
+++ b/doc/api/methods/logs.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/logs@
 
+UUID type: @57u5n@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Creation

diff --git a/doc/api/methods/nodes.html.textile.liquid b/doc/api/methods/nodes.html.textile.liquid
index 4ccbd999a2b04ca033084d03493570665b3e40c5..e5cb80a15e553d86e14d65ffa49cdf259ad38f86 100644 (file)
--- a/doc/api/methods/nodes.html.textile.liquid
+++ b/doc/api/methods/nodes.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/nodes@
 
+UUID type: @7ekkf@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/pipeline_instances.html.textile.liquid b/doc/api/methods/pipeline_instances.html.textile.liquid
index 97bf59ac8ade04c03e761b34a4d4aedfdf71606d..cacdaca71b55cb83b57cfd6bbd9cc25ebc28f8b1 100644 (file)
--- a/doc/api/methods/pipeline_instances.html.textile.liquid
+++ b/doc/api/methods/pipeline_instances.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/pipeline_instances@
 
+UUID type: @d1hrv@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/pipeline_templates.html.textile.liquid b/doc/api/methods/pipeline_templates.html.textile.liquid
index d44ee7b0c3b3844c10ae106c1c1fd47699529119..672b274c8bc95984c6bbb890e0ed767131c0c74d 100644 (file)
--- a/doc/api/methods/pipeline_templates.html.textile.liquid
+++ b/doc/api/methods/pipeline_templates.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/pipeline_templates@
 
+UUID type: @p5p6p@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/repositories.html.textile.liquid b/doc/api/methods/repositories.html.textile.liquid
index d2dcdc04f7392c8f0a8c6b90920da8c5a0c2b67e..d74570336bd2eea75f8942b3ac43cc7b3b8ea26a 100644 (file)
--- a/doc/api/methods/repositories.html.textile.liquid
+++ b/doc/api/methods/repositories.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/repositories@
 
+UUID type: @s0uqq@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/specimens.html.textile.liquid b/doc/api/methods/specimens.html.textile.liquid
index 79ef47965336156ac78c2cfc8bc10fdae130f055..55a7b0c6a94446ea1bbff67411a0489dc6117894 100644 (file)
--- a/doc/api/methods/specimens.html.textile.liquid
+++ b/doc/api/methods/specimens.html.textile.liquid
@@ -8,6 +8,8 @@ title: "specimens"
 
 See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
 
+UUID type: @j58dm@
+
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/specimens@
 
 Required arguments are displayed in %{background:#ccffcc}green%.

diff --git a/doc/api/methods/traits.html.textile.liquid b/doc/api/methods/traits.html.textile.liquid
index 0f997726d7c6ae925e9e37178b27312f57c3e919..9ed0df2a3e1fa0b2b6ae51ba6159d525a4005df0 100644 (file)
--- a/doc/api/methods/traits.html.textile.liquid
+++ b/doc/api/methods/traits.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/traits@
 
+UUID type: @q1cn2@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/users.html.textile.liquid b/doc/api/methods/users.html.textile.liquid
index 81e49c01d453d5d9222c41b11c7703db9e9b873f..25eac28118ca676c7f5ebd58f3351b92957eda50 100644 (file)
--- a/doc/api/methods/users.html.textile.liquid
+++ b/doc/api/methods/users.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/users@
 
+UUID type: @tpzed@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/virtual_machines.html.textile.liquid b/doc/api/methods/virtual_machines.html.textile.liquid
index 738465970643e678567511af2ac348b790798ab8..b3533254935ae8f6ba1545b277e7c6244b8d4599 100644 (file)
--- a/doc/api/methods/virtual_machines.html.textile.liquid
+++ b/doc/api/methods/virtual_machines.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/virtual_machines@
 
+UUID type: @2x53u@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/methods/workflows.html.textile.liquid b/doc/api/methods/workflows.html.textile.liquid
index 16755ce69e3f079a67870a033b80ace4fd91d7a3..17fb351599477c3287680f629564f8ff0137571c 100644 (file)
--- a/doc/api/methods/workflows.html.textile.liquid
+++ b/doc/api/methods/workflows.html.textile.liquid
@@ -10,6 +10,8 @@ See "REST methods for working with Arvados resources":{{site.baseurl}}/api/metho
 
 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/workflows@
 
+UUID type: @7fd4e@
+
 Required arguments are displayed in %{background:#ccffcc}green%.
 
 h2. Resource

diff --git a/doc/api/tokens.html.textile.liquid b/doc/api/tokens.html.textile.liquid
new file mode 100644 (file)
index 0000000..458c41b
--- /dev/null
+++ b/doc/api/tokens.html.textile.liquid
@@ -0,0 +1,21 @@
+---
+layout: default
+navsection: api
+title: API Authorization
+...
+
+All requests to the API server must have an API token.  API tokens can be issued by going though the login flow, or created via the API.  At this time, only browser based applications can perform login from email/password.  Command line applications and services must have an API token provided via the @ARVADOS_API_TOKEN@ environment variable or configuration file.
+
+h2. Browser login
+
+Browser based applications can perform log in via the following flow:
+
+# The web application presents a "login" link to @/login@ on the API server with a @return_to@ parameter provided in the query portion of the URL.  For example @https://{{ site.arvados_api_host }}/login?return_to=XXX@ , where  @return_to=XXX@ is the URL of the login page for the web application.
+# The "login" link takes the browser to the login page (this may involve several redirects)
+# The user logs in.  API server authenticates the user and issues a new API token.
+# The browser is redirected to the login page URL provided in @return_to=XXX@ with the addition of @?api_token=xxxxapitokenxxxx@.
+# The web application gets the login request with the included API token.
+
+h2. Creating tokens via the API
+
+Use the @create@ method of the "API client authorizations":{{site.baseurl}}/api/methods/api_client_authorizations.html resource.