QUICKSTART.rst

Warning

This API is preliminary, and it will change.

Adama Quickstart

Follow this quickstart with any HTTP client. Here we'll use curl.

The base url of the Adama is https://api.araport.org/collective/v0.2.

You need to obtain a token through your method of choice. In what follows, the environment variable TOKEN is assumed to be set to such token. It is convenient to set it as:

$ export TOKEN=my-token

Checking access to Adama

A GET request to https://api.araport.org/collective/v0.2/query should return:

$ curl -L -X GET https://api.araport.org/collective/v0.2/query \
   -H "Authorization: Bearer $TOKEN"
{
    "api": "Adama v0.2"
}

Registering an Adapter

Writing the adapter

Write a Python module main.py, with a function process that takes a JSON object as argument in the form of a dictionary. Print JSON objects to standard output, separated by the characters "---", and print "END" when finished.

For example:

# file: main.py

import json

def process(arg):
    print json.dumps({'one': 'object'})
    print "---"
    print json.dumps({'another': arg})
    print "END"

This function can be tested in the Python interpreter:

>>> import main
>>> main.process({'query': 5})
{"one": "object"}
---
{"another": {"query": 5}}
END

Registering

To register this adapter with the name example, we POST to https://api.araport.org/collective/v0.2/register with the following data:

• name (mandatory): the name of the adapter (example in this case),
• version (optional): version (default 0.1),
• url (mandatory): URL of the external service (http://example.com in this case),
• notify (optional): URL to notify with a POST request when the adapter is ready to use,
• code: module main.py.

Using curl:

$ curl -L -X POST https://api.araport.org/collective/v0.2/register \
    -F "name=example" -F "url=http://example.com" -F code=@main.py \
    -F "notify=https://my.url" \
    -H "Authorization: Bearer $TOKEN"
{
    "message": "registration started; will POST to 'http://my.url' when ready.\nGET to 'https://api.araport.org/collective/v0.2/manage/example_v0.1/state' to query for adapter state",
    "name": "example_v0.1",
    "status": "success"
}

At this point the registration procedure is started in the server. It may take some time, and in the meantime the state of the adapter can be checked with:

$ curl -L -X GET https://api.araport.org/collective/v0.2/manage/example_v0.1/state \
   -H "Authorization: Bearer $TOKEN"
{
    "state": "[1/4] Empty adapter created",
    "status": "success"
}

When ready, Adama will post to the url specified in the notify parameter (if any), and the adapter can be seen in the directory of services. To see a list of all the available services:

$ curl -L -X GET https://api.araport.org/collective/v0.2/register \
   -H "Authorization: Bearer $TOKEN"
{
    "adapters": [
        {
            "identifier": "example_v0.1",
            "language": "python",
            "name": "example",
            "url": "http://example.com",
            "version": "0.1",
            "workers": [
                "25be3f74b075c2753ce6690502f41caf61464b6c71096251eed16b1ad5a8c964"
            ]
        }
    ],
    "status": "success"
}

In this case, the service has one worker attending query requests.

Performing a query

By doing a POST to the https://api.araport.org/collective/v0.2/query we can reach the example adapter previously registered.

For example:

$ curl -L -X POST https://api.araport.org/collective/v0.2/query \
   -d '{"serviceName": "example_v0.1", \
        "query": {"value": 3}}' \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json"
{"result": [
{"one": "object"}
, {"another": {"count": false, "query": {"value": 3}, "worker": "0af609080636", "page": 1, "pageSize": 100}}
],
"metadata": {"time_in_main": 0.0013320446014404297},
"status": "success"}

Notice that the result consists of the two objects generated by main.py, one of which is including the query argument (in this case containing some extra metadata added by Adama).

Removing the adapter

An adapter can be deleted by using the verb DELETE to https://api.araport.org/collective/v0.2/register:

$ curl -L -X DELETE https://api.araport.org/collective/v0.2/register \
   -F "name=example_v0.1" \
   -H "Authorization: Bearer $TOKEN" \
{
    "message": "adapter example_v0.1 deleted",
    "status": "success"
}