Installing a web service adapter on Araport

×

Status message

New Feature: Guest Login function added to facilitate site exploration without registering. Try it out!

This blog tracks us as we install an Araport web service. We will use the Adama command line interface. We will install a web service adapter that still needs work but is ready for testing. We will mostly use 'curl' commands within a unix terminal.

Agave and Adama

We will interact with both of these web services running on Araport servers. Agave manages Araport user profiles, user permissions, user file space, etc. Adama manages Araport web services and allows users to manage their own web services. Both services offer an API that is available to us.

Use bash

Unix terminal users have their choice of shells, and most users have their preference, but bash is recommended. We will switch from our default shell, tcsh, to bash.

Then we set some environment variables that will reduce typing as as we interact with Araport. One environment variable is TOKEN. Using a TOKEN is easier and more secure than passing username & password on every command. The TOKEN shown is no longer valid; you must generate your own. How do we get a TOKEN? Log in to www.Araport.org, find MyAccount on the menu, and a tab called Agave (it may get renamed). Just for fun, we'll test an invalid TOKEN.

In the session example below, the text left of the dollar sign is the unix command prompt.

tcsh$ bash
bash$
bash$ export ARAPORT=https://api.araport.org
bash$ export ADAMA=$ARAPORT/community/v0.3
bash$ export TOKEN=d91a3e91ce1cb13bd973dd5d91e0453
bash$ BEARER="Authorization: Bearer $TOKEN"
# What happens if we use an invalid token?
bash$ curl -Lk -X GET -H "$BEARER" $ADAMA/namespaces
... html tags... Runtime Error ... Access Token Inactive...
bash$ 

Use curl

We will interact with the Adama API using the curl unix command. First, we check Adama for status == success. Then, we ask for a list of namespaces. Every Araport web service belongs to a namespace. The Araport display of web services allows users to search by namespace. Also, Araport inserts the namespace in the URL of every Araport web service. That allows multiple web services to use identical service endpoint names without conflict. (For example, if 'costco' and 'walmart' both have a 'groceries' service with a 'list' endpoint, then "URL/costco/groceries/list" and "URL/wallmart/groceries/list" would not conflict.)

bash$ curl -kL -X GET -H "$BEARER" $ADAMA/status
{
    "api": "Adama v0.3", 
    "hash": "d7cd335c577b6d55094430f2c8c22d46c2b632c7", 
    "status": "success"
}
bash$ curl -Lk -X GET -H "$BEARER" $ADAMA/namespaces
... big list here ...

Register a namespace

We chose ‘pmr’ as our namespace. (Our web service is an adapter for data provided by a 3rd party web site called PMR. The data provider is PMR at Iowa State University. After checking that our namespace is not already taken, we register our namespace.) Just for fun, we create it, delete it, and re-create it. We are human and we make some mistakes along the way. Some of the unix commands are very long; these may wrap in your browser window but they were typed on one line.

bash$ curl -Lk -X POST -H "$BEARER" -F name=pmr -F description="Plant Microbial Systems Resource"  $ADAMA/namespaces
{
    "result": "https://api.araport.org/community/v0.3/pmr", 
    "status": "success"
}
# try to delete but goof the parameter
bash$ curl -Lk -X DELETE -H "$BEARER"  $ADAMA/pmr/services
{
    "status": "success"
}
# try again
bash$ curl -Lk -X DELETE -H "$BEARER"  $ADAMA/pmr
{
    "status": "success"
}
# Is it gone?
bash$ curl -Lk -X GET -H "$BEARER"  $ADAMA/pmr/services
{
    "exception": "APIException", 
    "message": "API error: namespace not found: pmr", 
    "status": "error"
}
# Try to recreate it but goof the target name
bash$ curl -Lk -X POST -H "$BEARER" -F name=pmr -F description="Plant Microbial Systems Resource"  $ADAMA/pmr
{
    "exception": "MethodNotAllowed", 
    "message": "", 
    "status": "error", 
    "worker_trace": null
}
# Try again.
bash$ curl -Lk -X POST -H "$BEARER" -F name=pmr -F description="Plant Microbial Systems Resource"  $ADAMA/namespaces
{
    "result": "https://api.araport.org/community/v0.3/pmr", 
    "status": "success"
}
bash$ curl -Lk -X GET -H "$BEARER"  $ADAMA/pmr/services
... big list here...

Register the web service

We are ready! We have a namespace. We have our code on GitHub. We are ready to install on Araport. When we install it, the service returns JSON that lists all the endpoints. The JSON contains some interesting information. We notice that the URLs are formatted as {araport}/{api name and version}/{my namespace}/{my service name and version number}/{endpoint}. Our service name version number is v0.1; that number had not been provided by 'curl', so where did it come from? It was given in the metadata.yml file at GitHub. Our service has two endpoints: /list and /search; these are among the standard endpoints implemented by Adama. These endpoints will appear whether or not our python code at GitHub implements them; in fact, our python code includes a function starting with def search(args): but does not include anything like def list(args):.

bash$ curl -Lk -X POST -H "$BEARER" -F "git_repository=https://github.com/Arabidopsis-Information-Portal/PMR_API.git" $ADAMA/pmr/services
{
    "message": "registration started", 
    "result": {
        "list_url": "https://api.araport.org/community/v0.3/pmr/pmr_demo_api_v0.1/list", 
        "notification": "", 
        "search_url": "https://api.araport.org/community/v0.3/pmr/pmr_demo_api_v0.1/search", 
        "state_url": "https://api.araport.org/community/v0.3/pmr/pmr_demo_api_v0.1"
    }, 
    "status": "success"
}

Are we allowed to re-register (overwrite) an existing web service? No. Are we allowed to delete an existing web service? Yes. Can we delete somebody else's web service? No (not shown).

# What if we repeat the command? Not allowed.
bash$ curl -Lk -X POST -H "$BEARER" -F "git_repository=https://github.com/Arabidopsis-Information-Portal/PMR_API.git" $ADAMA/pmr/services
{
    "exception": "APIException", 
    "message": "API error: service slot not available: pmr.pmr_demo_api_v0.1\nCurrent state: ready", 
    "status": "error"
}
# We visited www.Araport.org and confirmed the web service was working. 
# Just for fun, delete it.
bash$ curl -Lk -X DELETE -H "$BEARER"  $ADAMA/pmr/pmr_demo_api_v0.1
{
    "status": "success"
}
# We visited Araport and confirmed the web service was gone.