allow optional headers on access_url (resolves issue #239)

docs/asciidoc/front_matter.adoc

@@ -34,8 +34,27 @@ For convenience, we define a recommended syntax for fully referencing DRS-access
 
 The DRS API specification is written in OpenAPI and embodies a RESTful service philosophy.  It uses JSON in requests and responses and standard HTTP/HTTPS for information transport.
 
-== Authorization & Authentication (WORK IN PROGRESS)
-
-Users must supply credentials that establish their identity and authorization in order to use a DRS endpoint. We recommend that DRS implementations use an OAuth2 https://oauth.net/2/bearer-tokens/[bearer token], although they can choose other mechanisms if appropriate. DRS callers can use the `auth_instructions_url` from the https://ga4gh.github.io/data-repository-service-schemas/#/DataRepositoryService/GetServiceInfo[service-info endpoint] to learn how to obtain and use a bearer token for a particular implementation.
-
-The DRS implementation is responsible for checking that a user is authorized to submit requests. The particular authorization policy is up to the DRS implementer.
+== Authorization & Authentication
+
+=== Making DRS Requests 
+
+The DRS implementation is responsible for defining and enforcing an authorization policy that determines which users are allowed to make which requests. We recommend that DRS implementations use an OAuth2 https://oauth.net/2/bearer-tokens/[bearer token], although they can choose other mechanisms if appropriate. DRS callers can use the `auth_instructions_url` from the https://ga4gh.github.io/data-repository-service-schemas/#/DataRepositoryService/GetServiceInfo[service-info endpoint] to learn how to obtain and use a bearer token for a particular implementation.
+
+=== Fetching DRS Objects
+
+The DRS API allows implementers to support a variety of different content access policies, depending on what `AccessMethod` s they return:
+
+* public content:
+** server provides an `access_url` with a `url` and no `headers`
+** caller fetches the object bytes without providing any auth info
+* private content that requires the caller to have out-of-band auth knowledge (e.g. service account credentials):
+** server provides an `access_url` with a `url` and no `headers`
+** caller fetches the object bytes, passing the auth info they obtained out-of-band
+* private content that requires the caller to pass an Authorization token:
+** server provides an `access_url` with a `url` and `headers`
+** caller fetches the object bytes, passing auth info via the specified header(s)
+* private content that uses an expensive-to-generate auth mechanism (e.g. a signed URL):
+** server provides an `access_id`
+** caller passes the `access_id` to the `/access` endpoint
+** server provides an `access_url` with the generated mechanism (e.g. a signed URL in the `url` field)
+** caller fetches the object bytes from the `url` (passing auth info from the specified headers, if any)

openapi/data_repository_service.swagger.yaml

@@ -24,7 +24,9 @@ security:
 paths:
   '/service-info':
     get:
-      summary: Returns service version and other information
+      summary: Get information about this implementation.
+      description: >-
+        May return service version and other information.
       operationId: GetServiceInfo
       responses:
         '200':
@@ -73,7 +75,9 @@ paths:
       x-swagger-router-controller: ga4gh.drs.server
   '/objects/{object_id}':
     get:
-      summary: Retrieve a Data Object
+      summary: Get info about a Data Object.
+      description: >-
+        Returns object metadata, and a list of access methods that can be used to fetch object bytes.
       operationId: GetObject
       responses:
         '200':
@@ -110,13 +114,15 @@ paths:
       x-swagger-router-controller: ga4gh.drs.server
   '/objects/{object_id}/access/{access_id}':
     get:
-      summary: Returns a fully resolvable URL that can be used to fetch the actual object bytes.
+      summary: Get a URL for fetching bytes. 
+      description: >-
+        Returns a fully resolvable URL that can be used to fetch the actual object bytes.
       operationId: GetAccessURL
       responses:
         '200':
           description: The access URL was found successfully.
           schema:
-            $ref: '#/definitions/GetAccessURLResponse'
+            $ref: '#/definitions/AccessURL'
         '400':
           description: The request is malformed.
           schema:
@@ -146,7 +152,7 @@ paths:
           in: path
           required: true
           type: string
-          description: An 'access_id' from 'access_methods' list of a Data Object
+          description: An `access_id` from the `access_methods` list of a Data Object
       tags:
         - DataRepositoryService
       x-swagger-router-controller: ga4gh.drs.server
@@ -319,13 +325,22 @@ definitions:
     properties:
       object:
         $ref: '#/definitions/Object'
-  GetAccessURLResponse:
+  AccessURL:
     type: object
-    required: ['object']
+    required: ['url']
     properties:
-      access_url:
+      url:
         type: string
-        description: A fully resolvable access_url that can be used to fetch the actual object bytes.
+        description: A fully resolvable URL that can be used to fetch the actual object bytes.
+      headers:
+        type: array
+        items:
+          type: string
+        description: >-
+          An optional list of headers to include in the HTTP request to `url`.
+          These headers can be used to provide auth tokens required to fetch the object bytes.
+        example:
+          Authorization: Basic Z2E0Z2g6ZHJz
   AccessMethod:
     type: object
     required:
@@ -348,20 +363,19 @@ definitions:
         description: >-
           Type of the access method.
       access_url:
-        type: string
+        $ref: '#/definitions/AccessURL'
         description: >-
-          A fully resolvable URL string that can be used to fetch the actual object bytes.
-          Note that at least one of access_url and access_id must be provided.
+          An `AccessURL` that can be used to fetch the actual object bytes.
+          Note that at least one of `access_url` and `access_id` must be provided.
       access_id:
         type: string
         description: >-
-          An arbitrary string to be passed to the /access path to fetch an access_url.
+          An arbitrary string to be passed to the /access path to get an `AccessURL`.
           This must be unique per object.
-          Note that at least one of access_url and access_id must be provided.
+          Note that at least one of `access_url` and `access_id` must be provided.
       region:
         type: string
         description: >-
-          OPTIONAL
           Name of the region in the cloud service provider that the object belongs to.
         example:
           us-east-1