Arvados

suggest classifying resources something like this

• api_client_authorizations
• api_clients
• authorized_keys
• users

• collections
• repositories

• links
• logs
• nodes
• keep_disks
• keep_services
• virtual_machines

• container_requests
• containers
• workflows
• groups

• jobs
• job_tasks
• pipeline_instances
• pipeline_templates

• humans
• specimens
• traits

10346-rearrange-api-docs

Overhaul API documentation. Major changes:

• Combine "method" and "schema" pages for each resource type.
• Document login and creation of API tokens
• Document specific HTTP syntax of requests
• Replace confusing permission model page with specification from wiki
• Add new page sketching out how storage and retrieval work for Keep, and added documentation about locator and manifest format from wiki
• Add new page sketching out containers vs. jobs API and how to use them
• Add a sentence or two to each resource to explain what it is
• Add consistent set of API usage examples for every SDK.

API documentation

Layout related

• Should the schema directory and all files in it be removed?

API Authorization page: This still feels like there are gaps here. A few questions / comments to dig deeper:

• "Command line applications and services must have an ..." -> may be "must use an ..." ?

• Browser login - This section obviously is too simplified without the mention of OAuth, SSO etc. May it should say something along those lines in "this may involve several redirects" and also add a disclaimer that "a highlevel login flow" rather than sounding like this is the entire picture here. A more descriptive section with google Auth SSO with a diagram can be considered

• "Creating tokens via the API" - Since invoking any API itself requires a token, I think this requires further explanation. Can you add explanation as to how to get the "first" token / admin token etc before one can invoke the create method?

• Trusted API tokens:
  • The first line is missing link to "api_clients" resource
  • First line should say " may create or list or API tokens" instead of " may create or list or API tokens"?
  • A few typos in this section
  • Can you add details as to how to mark a client as "trusted"?

Request Syntax page

• Any specific reason why the first introductory line or this entire page omits "REST"? I think this page can be much easier to understand if we say API server exposes REST API

• I recommend renaming it as "Making API requests" or "REST Request syntax" (see below about api_client_authorizations resource)

• In the examples, there are a few hard-coded tokens and hosts, and a few that say $ARVADOS_API_TOKEN etc

  curl -X DELETE -v -H "Authorization: OAuth2 ... " https://192.168.5.2:8000/arvados...

  curl -v -X POST --data-urlencode 'collection={"name":"empty collection"}' -H "Authorization: OAuth2 $ARVADOS_API_TOKEN" https://$ARVADOS_API_HOST/arvados/v1/collections | jq .

• For each section such as "Request URI" having a small example highlighting the specific thing would help

• Authorization header: can you replace the example with one of the full "curl" command examples? Something like "curl -v -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" ... "

• In the examples section:
  • Can you use a different filter (or pdh) in the list examples rather than a uuid that results in "items_available=1"?

• Can you show "create" example before the "update a field" example?

Common resource methods page

• "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. Arguments specifying a Location of query are incorporated into the query portion of the URI or request body." => Please add examples for each highlighting Location and Query

• Create - "Note that only the listed attributes (and standard metadata) are set, unset attributes will get default values, and the attributes of a given resource type are fixed (you cannot introduce new toplevel attributes)." => Please break this into three sentences or three bullet points, and preferably with an example. (For example, you cannot introduce new toplevel can have an example "name" on a "Job" resource

• For create, can the "object" be sent in "query" (Locator). I think this should be "post body"?

• "The delete method deletes a object .." => "an object"

• "All resources support listing with unless otherwise noted" => typo ("with unless"), and hard to read. Please consider "all resources support "list" method unless ..."

• "May also be subject to server limit" => "if not provided, server limit will be used"?

• "Skip the first ‘offset’ resources" => "Skip the first 'offset' number of resources"?

• "Conditions for selecting resources to return (see below)" => Replace "see below" with a link to filters section?

• Filters
  • It is hard to see that this is a sub-section of "List" section. Can we you use "Filters to list method" or something? Same with "Results" as well. May be "Results of a List request"?
  • Please include an example query with filters here

• For all the methods, I think adding an example request would be great

Common resource fields page

• "may be updated explicitly" => "may be updated explicitly by an admin user" ?

Permission model

• "the object is not returned by any list query" => Can you say something like "the object is not included in any list query responses"?

• In the "Anonymous user and group" can we also list the anonymous group uuid?

Storage in Keep

• In this page, it is confusing who / what the "client" is and one might wonder if it is the end user who is putting or fetching data. You might want to add a little bit about "keep client" at the beginning of the page clarifying it is the client programs that we implemented.

• In "fetching data" section, this is not making sense: "The server adds “token signatures” which provide proof of access for each block." Is it not the other way around? The client include the token signature in the request, which is validated in step 6?

• Rendezvous hashing: Please add the picture from Tom's "Keep_ some technical details" presentation with more explanation

• Keep locator format:
  • Please add an explanation as to what this section is talking about and an example above the "pre" code block.
  • Please remove extra lines in the pre block in this section to make it look tidy
  • You used "h1" for this section. Should be "h2" like other sections
  • I think the "Regular expressions ...", "Valid examples", "Invalid examples" need to be "h3" after that

• Regular expressions to validat locator: typo in this title (validator). Do we need this here in this documentation

• Can you please rename "Valid examples" as "Valid locators"? Same with "Invalid examples"

Manifest v1

• Please add examples here. One small example and one with directories and multiple blocks etc would be great

• "The second token is a data blob locator (see Keep locator format)" => I'd assume you wanted a link to "Keep locator format" here?

• Do you want to add "table(table table-bordered table-condensed)." to the table in "Invalid examples"

Computing with Crunch

• "The system will fulfill the container request by creating a Container object or, if the same request has been submitted in the past, reusing an existing container" => It would be helpful if you break this into two sentences first one saying "creating and reusing" and the second explaining how reused container is found. Also a typo

• "The dispatcher process will notice a new container in Queued state and submit a container executor to the underyling ..." => typo in "underlying"

• "Retrieve the container object; the output field contains the portable data hash of collection with the output files of the container." => This sentence needs a bit reworking

api_client_authorizations resource

• In all resources such as api_client_authorizations, "See REST methods for working with Arvados resources" is pointing to "See Common resource methods". Either this is pointing to incorrect page (instead of Request syntax page) or it should say something "see common methods ..." instead

• It would be good to add description to user_id that this represents the user to whom this token belongs

• "Be aware that requests for listing GET /arvados/v1/collections (no / suffix) will be rejected, because it is not an exact match with GET /arvados/v1/collections/" => we might want to say "/arvados/v1/collections/" would work though

• "Regular users may only create self-owned API tokens, but may provide a restricted "scope"#scope" => Is this supposed to point to something

• "Gets a ApiClientAuthorization’s metadata by UUID" => "Gets an ..."

• I think it would be nice to add an example for "order" in the "list" method description of resources: "["created_at desc"]" (and others)

• This resource is missing "UUID type" which is present in other resource pages. Also, I am not sure if "UUID type" is understandable to people with any explanation. Please consider something like: "UUID type: ozdt8. For example, aaaaa-ozdt8-ccccccc (with ozdt8 highlighted)

authorized_keys

• Would be nice to add description for key_type, authorized_user_uuid, public_key

groups resource

• group_class: please also add role and corresponding explanation

users resource

• system: please add explanation and who can access this method

keep_services

• "The keep_services resource storage servers and proxies available ..." => seems like it is missing a few words. "The keep_services resource provides access to the storage servers and proxies available ..."

• please list the "service_type"s in description

• please remove the empty table under "accessible"

• create methods says "keep_disk" instead of "keep_service" as the first argument

links

• tail_uuid "Object UUID at the tail (start, source, origin) of this link", and head_uuid "Object UUID at the head (end, destination, target) of this link" => I don't think this is helpful to someone who knows nothing about links. Please consider something like "head_uuid is the object which is being referred to in this link; tail_uuid is the object which is acting / receiving the link behavior for this head_uuid". I think listing head_uuid first might help as well.

• link classes - provenance
  • can the first one be " x -> Collection where x is not a resource" or something?
  • the notes column is empty in the table. sh we remove the column then?
  • it probably would help understand better if we list "permission" table first (because we talked about permission model earlier and provenance had never been mentioned until now)

• link classes - permissions
  • Is there need to list can_read->job uuid and can_write->job uuid as well under Group->Job?

• create a new link could use a full example

• render_not_found can use some explanation

logs

• object_uuid deserves a description

• It feels like an example for create and get request might be helpful?

nodes

• may be there is room to add description for various attributes in the resource table or an example for create method

• ping => is "ping a node" or "ping nodes"? I think this can use some explanation: if I remember correctly, we only list recently pinged nodes etc

• job_uuid - "The UUID of the job that this node is assigned to work on. If you do not have permission to read the job, this will be null" => "this will be null" is a bit confusing. Do we want to say "a null value will be returned in get and list requests"?

virtual_machines

• "The virtual_machines resource lists nodes in the Arvados ..." => since we use nodes to mean something specific about nodes, this may be confusing. May be "lists development environments in the ... "?

• an example for create might be helpful

• in "logins" table -> virtual_machine_uuid and authorized_key_uuid are pointing to "schema/x" page. They should be pointing to "methods/x" pages instead

• "Get a list, for every virtual machine in the system, of SSH keys and account names that should be able to log in" => too tricky. Can we simplify, "for every vm in the system, get a list of ssh keys ..."

keep_disks

• ping => "ping a keep_disk" or "ping keep_disks"?

collections

• "See storage in Keep for details" is pointing to wrong page

• portable data hash - "The MD5 sum of the stripped manifest text" => doesn't say what a "stripped" manifest is, not even in the storage page

container_requests

• "Currently, container reuse is the default behavior and a mechanism to skip reuse is not supported." => Is this still true?

• There are many places throughout the documentation where usages such as "container’s output_path is (or is a subdirectory of) this mount target" are used. I think it would be easier to read if they said something like: "container’s output_path is this mount target or is a subdirectory of this mount target"

• seems like a formatting issue with "create" section title: "Methods h2(#create). create" is what is seen

• create -> container_request is pointing to schema page

containers

• seems like a formatting issue with "create" section title: "Methods h2(#create). create" is what is seen

• create -> container is pointing to schema page

workflows

• create -> container is pointing to schema page

jobs

• formatting issue "Methods h2. cancel

• create pointing to schema directory

jobs_tasks

• "A job task is a individually scheduled and task executed as part of an overall job" => typo (a individually) and also "scheduled and task executed" doesn't make sense

pipeline_instaces

• please add a link to templates page for pipeline_template_uuid row

SDK examples (I only briefly scanned these and didn't actually test / play with these):

sdk/python/example.html.textile.liquid

• I think it would desirable to use "4zz18" instead of "bbbbb" for collection examples here

• it might also help to add something like "here aaaaa is used as the site prefix" at the top of the page

ruby example:

• 1h2. list shown instead of list section heading

go example:

• would be desirable to use actual uuid type instead of "bbbbb" and also at the top of page say "aaaaa" is used as site prefix

Radhika Chippada wrote:

API documentation

Layout related

• Should the schema directory and all files in it be removed?

Yep, I was just keeping it around in case there was anything left to copy over.

API Authorization page: This still feels like there are gaps here. A few questions / comments to dig deeper:

• "Command line applications and services must have an ..." -> may be "must use an ..." ?

Done.

• Browser login - This section obviously is too simplified without the mention of OAuth, SSO etc. May it should say something along those lines in "this may involve several redirects" and also add a disclaimer that "a highlevel login flow" rather than sounding like this is the entire picture here. A more descriptive section with google Auth SSO with a diagram can be considered

I added a link to a wiki page that is a lot more specific.

• "Creating tokens via the API" - Since invoking any API itself requires a token, I think this requires further explanation. Can you add explanation as to how to get the "first" token / admin token etc before one can invoke the create method?

Added a sentence about that.

• Trusted API tokens:
  • The first line is missing link to "api_clients" resource
  • First line should say " may create or list or API tokens" instead of " may create or list or API tokens"?
  • A few typos in this section
  • Can you add details as to how to mark a client as "trusted"?

Done.

Request Syntax page

• Any specific reason why the first introductory line or this entire page omits "REST"? I think this page can be much easier to understand if we say API server exposes REST API

Done.

• I recommend renaming it as "Making API requests" or "REST Request syntax" (see below about api_client_authorizations resource)

How about "REST API syntax"

• In the examples, there are a few hard-coded tokens and hosts, and a few that say $ARVADOS_API_TOKEN etc

[...]

[...]

Fixed.

• For each section such as "Request URI" having a small example highlighting the specific thing would help

Done.

• Authorization header: can you replace the example with one of the full "curl" command examples? Something like "curl -v -H "Authorization: OAuth2 oz0os4nyudswvglxhdlnrgnuelxptmj7qu7dpwvyz3g9ocqtr" ... "

Done.

• In the examples section:
  • Can you use a different filter (or pdh) in the list examples rather than a uuid that results in "items_available=1"?

Done.

• Can you show "create" example before the "update a field" example?

I reordered the examples to match the order that the methods are listed on every other page.

Common resource methods page

• "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. Arguments specifying a Location of query are incorporated into the query portion of the URI or request body." => Please add examples for each highlighting Location and Query

• Create - "Note that only the listed attributes (and standard metadata) are set, unset attributes will get default values, and the attributes of a given resource type are fixed (you cannot introduce new toplevel attributes)." => Please break this into three sentences or three bullet points, and preferably with an example. (For example, you cannot introduce new toplevel can have an example "name" on a "Job" resource

• For create, can the "object" be sent in "query" (Locator). I think this should be "post body"?

• "The delete method deletes a object .." => "an object"

• "All resources support listing with unless otherwise noted" => typo ("with unless"), and hard to read. Please consider "all resources support "list" method unless ..."

• "May also be subject to server limit" => "if not provided, server limit will be used"?

• "Skip the first ‘offset’ resources" => "Skip the first 'offset' number of resources"?

• "Conditions for selecting resources to return (see below)" => Replace "see below" with a link to filters section?

• Filters
  • It is hard to see that this is a sub-section of "List" section. Can we you use "Filters to list method" or something? Same with "Results" as well. May be "Results of a List request"?

Done.

• Please include an example query with filters here

• For all the methods, I think adding an example request would be great

Going to pass on this because there are already examples in other sections and I need to get through this.

Common resource fields page

• "may be updated explicitly" => "may be updated explicitly by an admin user" ?

Regular users can change ownership (e.g. moving from one project to another) but added an explicit link to permission model page.

Permission model

• "the object is not returned by any list query" => Can you say something like "the object is not included in any list query responses"?

Done.

• In the "Anonymous user and group" can we also list the anonymous group uuid?

Done.

Storage in Keep

• In this page, it is confusing who / what the "client" is and one might wonder if it is the end user who is putting or fetching data. You might want to add a little bit about "keep client" at the beginning of the page clarifying it is the client programs that we implemented.

Done.

• In "fetching data" section, this is not making sense: "The server adds “token signatures” which provide proof of access for each block." Is it not the other way around? The client include the token signature in the request, which is validated in step 6?

Rewrote it to hopefully clarify.

• Rendezvous hashing: Please add the picture from Tom's "Keep_ some technical details" presentation with more explanation

I'm not sure where to find that presenation?

• Keep locator format:
  • Please add an explanation as to what this section is talking about and an example above the "pre" code block.

Done.

• Please remove extra lines in the pre block in this section to make it look tidy

Fixed.

• You used "h1" for this section. Should be "h2" like other sections
• I think the "Regular expressions ...", "Valid examples", "Invalid examples" need to be "h3" after that

Fixed.

• Regular expressions to validat locator: typo in this title (validator). Do we need this here in this documentation

Fixed.

• Can you please rename "Valid examples" as "Valid locators"? Same with "Invalid examples"

Fixed.

... Rest pending.

Please make sure that we have the source files for any diagrams/images which are used so that they can be modified and updated in the future.

Radhika Chippada wrote:

Manifest v1

• Please add examples here. One small example and one with directories and multiple blocks etc would be great

Done.

• "The second token is a data blob locator (see Keep locator format)" => I'd assume you wanted a link to "Keep locator format" here?

Done.

• Do you want to add "table(table table-bordered table-condensed)." to the table in "Invalid examples"

Done.

Computing with Crunch

• "The system will fulfill the container request by creating a Container object or, if the same request has been submitted in the past, reusing an existing container" => It would be helpful if you break this into two sentences first one saying "creating and reusing" and the second explaining how reused container is found. Also a typo

Done

• "The dispatcher process will notice a new container in Queued state and submit a container executor to the underyling ..." => typo in "underlying"

Fixed.

• "Retrieve the container object; the output field contains the portable data hash of collection with the output files of the container." => This sentence needs a bit reworking

Rewrote it to refer to the pending output_uuid field.

Radhika Chippada wrote:

api_client_authorizations resource

• In all resources such as api_client_authorizations, "See REST methods for working with Arvados resources" is pointing to "See Common resource methods". Either this is pointing to incorrect page (instead of Request syntax page) or it should say something "see common methods ..." instead

Fixed.

• It would be good to add description to user_id that this represents the user to whom this token belongs

I don' think this field should be exposed in the API, see #10405

• "Be aware that requests for listing GET /arvados/v1/collections (no / suffix) will be rejected, because it is not an exact match with GET /arvados/v1/collections/" => we might want to say "/arvados/v1/collections/" would work though

Actually, "/arvados/v1/collections/" gets rejected too. It looks like the trailing "/" gets trimmed. Added a note about this behavior.

• "Regular users may only create self-owned API tokens, but may provide a restricted "scope"#scope" => Is this supposed to point to something

Fixed.

• "Gets a ApiClientAuthorization’s metadata by UUID" => "Gets an ..."

Fixed.

• I think it would be nice to add an example for "order" in the "list" method description of resources: "["created_at desc"]" (and others)

I removed the duplicated arguments for "list" and linked them to the common method section, which does have an example of "order".

• This resource is missing "UUID type" which is present in other resource pages. Also, I am not sure if "UUID type" is understandable to people with any explanation. Please consider something like: "UUID type: ozdt8. For example, aaaaa-ozdt8-ccccccc (with ozdt8 highlighted)

Fixed.

authorized_keys

• Would be nice to add description for key_type, authorized_user_uuid, public_key

Done.

groups resource

• group_class: please also add role and corresponding explanation

? there's no "role" field ??

users resource

• system: please add explanation and who can access this method

Added brief documentation.

keep_services

• "The keep_services resource storage servers and proxies available ..." => seems like it is missing a few words. "The keep_services resource provides access to the storage servers and proxies available ..."

Fixed.

• please list the "service_type"s in description

Done.

• please remove the empty table under "accessible"

Done.

• create methods says "keep_disk" instead of "keep_service" as the first argument

Fixed.

links

• tail_uuid "Object UUID at the tail (start, source, origin) of this link", and head_uuid "Object UUID at the head (end, destination, target) of this link" => I don't think this is helpful to someone who knows nothing about links. Please consider something like "head_uuid is the object which is being referred to in this link; tail_uuid is the object which is acting / receiving the link behavior for this head_uuid". I think listing head_uuid first might help as well.

Updated text.

• link classes - provenance
  • can the first one be " x -> Collection where x is not a resource" or something?
  • the notes column is empty in the table. sh we remove the column then?
  • it probably would help understand better if we list "permission" table first (because we talked about permission model earlier and provenance had never been mentioned until now)

I removed these because we don't actually use them.

• link classes - permissions
  • Is there need to list can_read->job uuid and can_write->job uuid as well under Group->Job?

I removed this and linked to the permission model page.

• create a new link could use a full example

Going to pass on this, the create method is the same as every other one.

• render_not_found can use some explanation

Removed it, not sure what it is doing there.

logs

• object_uuid deserves a description

Done.

• It feels like an example for create and get request might be helpful?

Pass (also case where create/get are not special).

nodes

• may be there is room to add description for various attributes in the resource table or an example for create method

I'm not sure of the term destiny for the nodes table in the crunch v2 world, I'm going to pass on adding more documentation right now.

• ping => is "ping a node" or "ping nodes"? I think this can use some explanation: if I remember correctly, we only list recently pinged nodes etc

Fixed.

• job_uuid - "The UUID of the job that this node is assigned to work on. If you do not have permission to read the job, this will be null" => "this will be null" is a bit confusing. Do we want to say "a null value will be returned in get and list requests"?

I that means that the job_uuid field will be null.

virtual_machines

• "The virtual_machines resource lists nodes in the Arvados ..." => since we use nodes to mean something specific about nodes, this may be confusing. May be "lists development environments in the ... "?

Changed "nodes" to "compute resources".

• an example for create might be helpful

(same)

• in "logins" table -> virtual_machine_uuid and authorized_key_uuid are pointing to "schema/x" page. They should be pointing to "methods/x" pages instead

Fixed.

• "Get a list, for every virtual machine in the system, of SSH keys and account names that should be able to log in" => too tricky. Can we simplify, "for every vm in the system, get a list of ssh keys ..."

Fixed.

keep_disks

• ping => "ping a keep_disk" or "ping keep_disks"?

Since this is obsolete I'm going to pass on this.

collections

• "See storage in Keep for details" is pointing to wrong page

Fixed.

• portable data hash - "The MD5 sum of the stripped manifest text" => doesn't say what a "stripped" manifest is, not even in the storage page

Reworded.

container_requests

• "Currently, container reuse is the default behavior and a mechanism to skip reuse is not supported." => Is this still true?

Nope, there's a use_existing field now. Updated.

• There are many places throughout the documentation where usages such as "container’s output_path is (or is a subdirectory of) this mount target" are used. I think it would be easier to read if they said something like: "container’s output_path is this mount target or is a subdirectory of this mount target"

Going to pass on this (this text is more recent), trying to focus on things that are out of date or missing.

• seems like a formatting issue with "create" section title: "Methods h2(#create). create" is what is seen

Fixed.

• create -> container_request is pointing to schema page

Fixed.

containers

• seems like a formatting issue with "create" section title: "Methods h2(#create). create" is what is seen

Fixed.

• create -> container is pointing to schema page

Fixed.

workflows

• create -> container is pointing to schema page

Fixed.

jobs

• formatting issue "Methods h2. cancel

Fixed

• create pointing to schema directory

Fixed.

jobs_tasks

• "A job task is a individually scheduled and task executed as part of an overall job" => typo (a individually) and also "scheduled and task executed" doesn't make sense

Fixed.

pipeline_instaces

• please add a link to templates page for pipeline_template_uuid row

Done

SDK examples (I only briefly scanned these and didn't actually test / play with these):

sdk/python/example.html.textile.liquid

• I think it would desirable to use "4zz18" instead of "bbbbb" for collection examples here

Fixed.

• it might also help to add something like "here aaaaa is used as the site prefix" at the top of the page

Done.

ruby example:

• 1h2. list shown instead of list section heading

Fixed.

go example:

• would be desirable to use actual uuid type instead of "bbbbb" and also at the top of page say "aaaaa" is used as site prefix

Done.

Now 10346-rearrange-api-docs @ ddeef8adc0cb7cdb55be644b9335ea51919ed513

At f6a8bf41

• In all pages: "See Common resource methods more information about ... " is missing "for" :(

API Reference

• "added a link to a wiki page that is a lot more specific" => This wiki page absolutely needs at least a high-level SSO diagram! I added a "Session establishment" drawing in our "Knowledge Sharing" folder in a new "Diagrams" folder. Please see if you like it and would like to add it to the wiki page. Please feel free to make any changes as you'd like. (Also moved the previous Permission diagram into this new folder)

API Authorization

• There are still a few examples with hard-coded "192.168.5.2:8000". Do we want to use "localhost" instead?

Storage in keep

• This page is so much more efficient now.

• "The server adds “token signatures” to the manifest_text, these signatures are used to prove to Keep servers that the client is permitted to read a given block" => This is still unclear. How about, "The API server returns the collection with manifest text. The server adds token signatures to the manifest text ...." ? It just is not clear right away that the client is making two separate (sets of) requests, first to the API server to get collection and then to the keepserver(s).

group resource

• "there's no "role" field" => I am wondering if we want to talk about the concept of "roles" (https://dev.arvados.org/projects/arvados/wiki/Groups_Projects_Ownership_and_Permissions_Specification)?

container_request resource

• "Currently, container reuse is the default behavior and a mechanism to skip reuse is not supported" => So this can be overridden passing a false for "use_existing"? If that is the case, can you not say "not supported" and instead say can be skipeed using "use_existing"?

Radhika Chippada wrote:

At f6a8bf41

• In all pages: "See Common resource methods more information about ... " is missing "for" :(

Fixed.

API Reference

• "added a link to a wiki page that is a lot more specific" => This wiki page absolutely needs at least a high-level SSO diagram! I added a "Session establishment" drawing in our "Knowledge Sharing" folder in a new "Diagrams" folder. Please see if you like it and would like to add it to the wiki page. Please feel free to make any changes as you'd like. (Also moved the previous Permission diagram into this new folder)

Added the diagram. Thanks!

API Authorization

• There are still a few examples with hard-coded "192.168.5.2:8000". Do we want to use "localhost" instead?

I don't think "localhost" would be any better. I'm going to leave it as is.

Storage in keep

• This page is so much more efficient now.

• "The server adds “token signatures” to the manifest_text, these signatures are used to prove to Keep servers that the client is permitted to read a given block" => This is still unclear. How about, "The API server returns the collection with manifest text. The server adds token signatures to the manifest text ...." ? It just is not clear right away that the client is making two separate (sets of) requests, first to the API server to get collection and then to the keepserver(s).

I moved the 2nd part of the sentence down to the step about requesting the blocks from keepstore. Thanks.

group resource

• "there's no "role" field" => I am wondering if we want to talk about the concept of "roles" (https://dev.arvados.org/projects/arvados/wiki/Groups_Projects_Ownership_and_Permissions_Specification)?

I see. Yea maybe, but I'm not sure what to add. Defer.

container_request resource

• "Currently, container reuse is the default behavior and a mechanism to skip reuse is not supported" => So this can be overridden passing a false for "use_existing"? If that is the case, can you not say "not supported" and instead say can be skipeed using "use_existing"?

Thanks for the catch. Fixed.

Now @ 1129e9428dc1f3a300c4148bf12821eecf511ab3

This version is much better. Thanks!

LGTM @ 1129e942

Oops just saw one formatting error I saw but failed to note earlier.

In container_requests page, under Resource, the last entry is not formatting correctly. Seeing this on the page:

@true@ @false@| |filters|string|Additional constraints for satisfying the container_request, given in the same form as the filters parameter accepted by the container_requests.list API.||

Please check it out. Thanks.