CIAT API¶

Global¶

• All resources are available via https only.
• All responses are in JSON. Graphics are created from the qcat application.
• Authentication is required for all requests.
• Authentication is probably done with the Authorization Header (token based)
• Default http response status codes are used (200, 403, 404, 500)
• Documentation is always good, it may be generated from the code (http://swagger.io)?

Resources¶

There are three resources:

• rainfall
• rainy-days
• temperature

Example¶

• URL: /[v1]/<resource>
• Method: GET
• Request params (in the get-querystring):

• years: comma separated list of integers
• coordinates: two points (WGS 84), comma separated (latitude, longitude)
• Example request: curl -X GET -H 'Authorization: Token 007' https://<domain>/api/v1/rainfall/?years=2010,2020,2050&coordinates=4.6,-47

• Response:

• Always include 'historic' data
• List of years, with monthly data:

[
historic: {
1: 25,
2: 48,
3: 194,
...
},
2010: {
1: 20,
2: 25,
3: 15,
...
},
2020: {
...
}
]

Error handling¶

To be defined.

• What happens in case some data is not available? Partial responses or no response at all?
• How verbose are request errors? e.g. request for invalid years, invalid coordinates
• What happens in case of request timeouts or long page loads?