REST API

HTTP requests can be sent to a Polytope server to submit data requests and poll their status, as well as to retrieve the data once it is ready for download. Although a bit tedious, it is the native, clientless way to interact with the server and it is used behind the scenes by the polytope-client Python API and command-line interface.

A basic example workflow is provided below. You can find more details in the REST API reference (v1) or at the /api/v1/openapi endpoint of an active polytope server.

Getting started

First, set up some environment variables to be used throughout the example.

export address=https://polytope.example.com
export port=443
export url=${address}:${port}
export user_email=polly@example.com
export user_key='4j3s3d34n4sn335jacf3n3d4f4g61635'

Check the Polytope server is up and running via GET to the /api/v1/test endpoint:

curl -i $url/api/v1/test
# HTTP/1.1 200 OK
# [...]
# {"message": "Polytope server is alive"}

Check the available collections via GET to the /api/v1/collections endpoint without authentication:

curl -i -X GET $url/api/v1/collections
# HTTP/1.1 401 UNAUTHORIZED
# [...]
# {"message": "Could not read authorization header, expected 'Authorization: <type> <credentials>"}

Repeat with authentication:

curl -i -X GET $url/api/v1/collections -H "Authorization: EmailKey $user_email:$user_key"
# HTTP/1.1 200 OK
# [...]
# {"message": ["collection1", "collection2"]}

Note

In this example, EmailKey authentication is used. You can replace it by Basic or Bearer authentication if your Polytope instance is configured with different authentication mechanisms. See Authentication and Authorization.

Making a request

Submit a request to one of the collections via POST to the /api/v1/requests/<collection-id>` endpoint:

request='{"verb":"retrieve","request":{"stream":"oper","levtype":"sfc","param":"165.128/166.128/167.128","step":"0","time":"00/06/12/18","date":"20150323","type":"an","class":"od","expver":"0001","domain":"g"}}'

curl -i -X POST $url/api/v1/requests/collection1 -H "Authorization: EmailKey $user_email:$user_key" -H "Content-Type: application/json" -d "$request"
# HTTP/1.1 202 ACCEPTED
# Location: https://polytope.example.com/api/v1/requests/dc2b6c27-a849-4787-91d0-df8dc9d25440
# [...]
# {"message": "Request queued", "status": "queued"}

Note

In this example, we assume that collection1 uses FDB as a datasource. The format of the request is a dictionary of meteorological keys which this particular FDB understands. See Collections and Datasources and the FDB documentation.

Poll the status of your request via GET to the /api/v1/requests/<request-id> endpoint:

curl -i -X GET $url/api/v1/requests/dc2b6c27-a849-4787-91d0-df8dc9d25440 -H "Authorization: EmailKey $user_email:$user_key"
# HTTP/1.1 202 ACCEPTED
# Location: https://polytope.example.com/api/v1/requests/dc2b6c27-a849-4787-91d0-df8dc9d25440
# [...]
# {"message": "Processing...", "status": "processing"}

# [...]

curl -i -X GET $url/api/v1/requests/dc2b6c27-a849-4787-91d0-df8dc9d25440 -H "Authorization: EmailKey $user_email:$user_key"
# HTTP/1.1 303 SEE OTHER
# Location: https://polytope.example.com/api/v1/downloads/default/dc2b6c27-a849-4787-91d0-df8dc9d25440
# [...]
# {"contentLength": 51409440, "location": "../downloads/default/dc2b6c27-a849-4787-91d0-df8dc9d25440", "contentType": "application/x-grib"}

Once the data is ready for download, retrieve it via GET to the /api/v1/downloads endpoint, as pointed to by the Location header in the latest status poll:

curl -X GET https://polytope.example.com/api/v1/downloads/default/dc2b6c27-a849-4787-91d0-df8dc9d25440 -H "Authorization: EmailKey $user_email:$user_key" -o data.grib

The data is ready to use.

Listing requests

List your active requests via GET to the /api/v1/requests endpoint:

curl -X GET $url/api/v1/requests -H "Authorization: EmailKey $user_email:$user_key" | python3 -m json.tool
# {
#     "message": [
#         {
#             "id": "dc2b6c27-a849-4787-91d0-df8dc9d25440",
#             "timestamp": 1635733165.370228,
#             "last_modified": 1635733171.258691,
#             "user": {
#                 "id": "14c3ff0d-ee9c-5583-8ab0-ca71d3801bad",
#                 "username": "polly",
#                 "realm": "example",
#                 "roles": [
#                     "all"
#                 ],
#                 "attributes": {}
#             },
#             "verb": "retrieve",
#             "url": "./downloads/default/dc2b6c27-a849-4787-91d0-df8dc9d25440",
#             "md5": null,
#             "collection": "collection1",
#             "status": "processed",
#             "user_message": "Success",
#             "user_request": "{'stream': 'oper', 'levtype': 'sfc', 'param': '165.128/166.128/167.128', 'step': '0', 'time': '00/06/12/18', 'date': '20150323', 'type': 'an', 'class': 'od', 'expver': '0001', 'domain': 'g'}",
#             "content_length": null
#         }
#     ]
# }

Revoking requests

Revoke the request via DELETE to the /api/v1/requests/<request-id> endpoint:

curl -i -X DELETE $url/api/v1/requests/dc2b6c27-a849-4787-91d0-df8dc9d25440 -H "Authorization: EmailKey $user_email:$user_key"
# HTTP/1.1 200 OK
# [...]
# {"message": "Successfully deleted request"}