Web API
=======

The following document outlines an overall design of the `RESTful <https://en.wikipedia.org/wiki/Representational_state_transfer>`_
`Web Service <http://en.wikipedia.org/wiki/Web_service>`_ implemented and provided by this system for access to various underlying
vector, raster and meta data.

Features of the API include:

- Versioned Access
- RESTful Architecture
- Multiple Output Formats
- Self Documenting and Traversing


Global Parameters
-----------------

All endpoints accept the following optional parameter(s):

- ``format``
  representation format.
  -- **Default:** ``json``


Global Help
-----------

All endpoints accept and implement a ``help`` resource that returns a document that describes the API endpoint being requested, what it does and what
data is provided. Example::

    /api/v1/help



Responses
---------

There are two types of responses. Normal responses are responses to any API endpoint that results in a valid response with data, a Help response is a response
to an API endpoint's help document describing what the API endpoint does and what data is provided by it.


Normal Responses
................

.. code-block:: json

    {
        data: [ ... ]
    }

Where:

- ``data``
  is a list (*possibly empty*) of data returned


Help Response
.............

A response describing the API endpoint being requested, what it does and the data provided.

.. note:: This can be requested in any supported format. e.g: text, html, json


Summaries
---------

This data can be used to explore region similarities and differences in tabular or graph form.

A single "resource" is a table of data for a given intersection of region type, year, future model, and emission scenario.
The resource includes summary data for every region of the given region type.

Endpoint: ``/summaries``

Structure::

    /summaries
    /summaries/projections
    /summaries/projections/scenario
    /summaries/projections/scenario/model
    /summaries/projections/scenario/model/year
    /summaries/projections/scenario/model/year/region
    /summaries/projections/scenario/model/year/var
    /summaries/projections/scenario/model/year/var/region

Where:

- ``model``
  a climate model

- ``scenario``
  an emissions scenario

- ``year``
  a future year

- ``var``
  a specific bio-climatic variable

- ``region``
  a collection of regions to intersect against


Examples(s)::

    GET /api/v1/summaries/projections/scenario/model/year/region
    GET /api/v1/summaries/projections/scenario/model/year/var/region



Variables
---------

This data describes various aspects of the bio-climatic variables that are given values in the region summaries, and/or displayed as WMS layers.  The data includes the variable's description, measurement units, and maximum and minimum (across all available summaries).

A single "resource" is a set of metadata for a particular variable.

Endpoint: ``/variables``

Structure::

    /variables
    /variables/var

Where:

- ``var``
  the name of a specific bio-climatic variable


Example 1::

    GET /api/v1/variables

will return a list of all variables, similar to::

    {
        data: [
            {
                id: "bio1",
                shortname: "Annual Precip",
                longname: "Mean Annual Precipitation",
                units: "mm",
                min: 3,
                max: 2456
            },
            {
                id: "bio2",
                shortname: "Annual Max Temp",
                longname: "Mean Annual Maximum Temperature",
                units: "C",
                min: 15,
                max: 48
            },
            ...
            { ... }
        ]
    }

Example 2::

    GET /api/v1/variables/bio2

Will return a similar list but containing just the specified variable::

    {
        data: [
            {
                id: "bio2",
                shortname: "Annual Max Temp",
                longname: "Mean Annual Maximum Temperature",
                units: "mm",
                min: 15,
                max: 48
            }
        ]
    }



Regions
-------

This data could be used by a client to describe a particular region in detail, including a geographic rendering of the borders of the region.
A single "resource" is a list of data for a given region.

Endpoint: ``/regions``

Structure::

    /regions/
    /regions/collection/
    /regions/collection/sub-collection
    /regions/collection/sub-collection/id

Where:

- ``collection``
  is a collection.

- ``subcollection``
  is a sub-collection of regions belonging to a parent collection.

- ``id``
  is a unique region belonging to a collection/sub-collection.

.. note::
   - Region hierarchy can be arbitrarily nested.

Examples::

    GET /api/v1/regions/
    GET /api/v1/regions/collection/
    GET /api/v1/regions/collection/subcollection/
    GET /api/v1/regions/collection/subcollection/id



Features
--------

Used to request and filter GeoJSON features from a vector data source such as a `Shapefile <http://en.wikipedia.org/wiki/Shapefile>`).

Endpoint: ``/features``


Geometry
--------

Used for server-side geometric operations (//buffer, intersection, union, etc//).

Endpoint: ``/geometry``


WMS
---

Standard `WMS <http://en.wikipedia.org/wiki/Web_Map_Service>`_ service for tile rendering of Raster and Vector layers.

Endpoint: ``/wms``