Documenting Parameters

Starting in version 0.3, Adama allows to document the parameters for all the types of adapters.

The user provided documentation is a backward compatible extension of the metadata file. The syntax for declaring parameters is based in Swagger 2.0. The full Swagger spec can be used in the endpoints field in the file metadata.yml, but a simpler subset is also supported, allowing easier documentation of the most common cases of adapters.

Example

The following is a basic example of an Adama adapter with autogenerated documentation. Refer to the base tutorial for instructions about registering an adapter, and change the base URL from api.araport.org to adama-dev.cloudapp.net (this is a sandbox, don’t worry to break things here).

This adapter is hosted at github.com/waltermoreira/sample-parameter-docs.

The git repository contains two files: main.py and metadata.yml. The file metadata.yml describes an adapter with four parameters:

---

name: my_adapter
type: query

validate_request: yes

endpoints:
  /search:
    parameters:
      - name: x
        description: Parameter X
        type: string
        required: true
      - name: y
        description: Parameter Y
        type: integer
        format: int64
        required: false
        default: 5
      - name: z
        description: Parameter Z
        type: array
        required: true
        collectionFormat: multi
        items:
          type: number
          format: double
      - name: w
        description: Parameter W
        type: string
        required: true
        enum:
          - Spam
          - Eggs

Let’s explain the meaning of the several sections.

Line 6 declares that the service wants Adama to validate the input before passing the control to the module main.py. The default is no, which allows for backward compatibility and gradual documentation of existing adapters. When Adama validates the input, the developer of the adapter can be confident that the arguments for the function main.search have the types specified in metadata.yml.

For example, the function main.search in this adapter contains the lines:

def search(args):
    # ...
    w = args['w']
    assert w in ('Spam', 'Eggs')
    # ...

When validate_request: yes, the developer knows that these two lines will not raise an error, since the parameter w is mandatory and it is one of the values described in the enumeration.

Lines 8-9 declare that we are documenting the endpoint /search of the service. Current Adama adapters have a defined list of supported endpoints (see live API docs), but the list can be expanded in the future.

Lines 11-14 describe the mandatory parameter x of type string.

Lines 15-20 describe the optional parameter y of type integer. In case it is not passed in the request, the adapter will get the default value 5.

Lines 21-28 describe a parameter z of type array of numbers. An array can be passed in a request in different ways. Line 25 declares that this adapter accepts a multi format. This means that a request of the form:

https://araport-dev.cloudapp.net/.../my_adapter_v0.1/search?z=2&z=3.1&z=10&...

will pass the array [2.0, 3.1, 10.0] to the function main.search. See the Swagger spec for the available ways to pass arrays in requests.

Lines 29-35 describe a parameter w with a defined set of possible values.

Registering the adapter

Register the adapter following the instructions in the base tutorial. Here is an example using the tool httpie [1] for performing the requests:

export ADAMA=https://adama-dev.cloudapp.net/community/v0.3
export TOKEN=...my token...
http POST https://$ADAMA/my_namespace/services \
    Authorization:"Bearer $TOKEN" \
    git_repository=https://github.com/waltermoreira/sample-parameter-docs \
    validate_request=yes

The adapter health can be checked with the request:

http https://$ADAMA/my_namespace/my_adapter_v0.1 Authorization:"Bearer $TOKEN"

which should return the a successful response with a lot of “nerd stats”.

Accessing the documentation

Once the adapter is successfully registered, the full Swagger documentation can be accessed in the /docs endpoint of the adapter. For example:

# return Swagger documentation in JSON format
http https://$ADAMA/my_namespace/my_service_v0.1/docs \
    Authorization:"Bearer $TOKEN"

# return Swagger documentation in YAML format
http https://$ADAMA/my_namespace/my_service_v0.1/docs?format=yaml \
    Authorization:"Bearer $TOKEN"

This output is usually not meant for human consumption (although the YAML output is very readable). The main goal of this endpoint is to be fed to any Swagger 2.0 complaint browser. Araport near future plans include to provide a developer console that will include all the adapters documentation, the Agave API, and the Adama base API. In the meantime, Adama provides the endpoint /docs/swagger which is a basic instance of a Swagger browser.

To interact with the documentation, access with the browser the URL:

https://adama-dev.cloudapp.net/community/v0.3/my_namespace/my_adapter_v0.1/docs/swagger

Footnotes

[1]	httpie is a strongly recommended replacement for curl: http://httpie.org/