WOCAT » QCAT

h1. CIAT API

h2. 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)?

h2. Resources

There are three resources:

* rainfall

* rainy-days

* temperature

h2. 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:

<pre>

[

historic: {

1: 25,

2: 48,

3: 194,

...

},

2010: {

1: 20,

2: 25,

3: 15,

...

},

2020: {

...

}

]

</pre>

h2. 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?