The following document outlines an overall design of the RESTful Web Service implemented and provided by this system for access to various underlying vector, raster and meta data.
Features of the API include:
All endpoints accept the following optional parameter(s):
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
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.
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
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:
Examples(s):
GET /api/v1/summaries/projections/scenario/model/year/region
GET /api/v1/summaries/projections/scenario/model/year/var/region
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:
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
}
]
}
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:
Note
Examples:
GET /api/v1/regions/
GET /api/v1/regions/collection/
GET /api/v1/regions/collection/subcollection/
GET /api/v1/regions/collection/subcollection/id
Used to request and filter GeoJSON features from a vector data source such as a Shapefile <http://en.wikipedia.org/wiki/Shapefile>).
Endpoint: /features
Used for server-side geometric operations (//buffer, intersection, union, etc//).
Endpoint: /geometry