[examples/openspending] - openspending v0.2 (#907)
* [examples/openspending] - openspending v0.2 * [examples/openspending][m] - fix build * [examples/openspending][xs] - fix build * [examples/openspending][xs] - add prebuild step * [examples/openspending][m] - fix requested by demenech * [examples/openspending][sm] - remove links + fix bug
This commit is contained in:
Luccas Mateus
GitHub
197
examples/openspending/content/help/rest.md
Normal file
197
examples/openspending/content/help/rest.md
Normal file
@@ -0,0 +1,197 @@
|
||||
---
|
||||
section: help
|
||||
lead: true
|
||||
title: REST resources
|
||||
authors:
|
||||
- Neil Ashton
|
||||
---
|
||||
OpenSpending pages generally support multiple representations, at least
|
||||
a user-facing HTML version and a JSON object that represents the contained
|
||||
data. For various technical and non-technical reasons, most of the data is
|
||||
read-only.
|
||||
|
||||
Content negotiation can be performed either via HTTP ``Accept`` headers or
|
||||
via suffixes in the resource URL. The following types are generally
|
||||
recognized:
|
||||
|
||||
* **HTML** (Hyptertext Markup), MIME type ``text/html`` or any value not
|
||||
otherwise in use, suffix ``.html``. This is the default representation.
|
||||
* **JSON** (JavaScript Object Notation), MIME type ``application/json`` and
|
||||
suffix ``.json``.
|
||||
* **CSV** (Comma-Separated Values), MIME type ``text/csv`` and suffix
|
||||
``.csv``. CSV is only supported where listings can be exported with some
|
||||
application-level meaning.
|
||||
|
||||
The key resources in OpenSpending are datasets, entries, dimensions, and
|
||||
dimension members. Each of these has a listing and an entity view that can
|
||||
be accessed.
|
||||
|
||||
#### Listing datasets
|
||||
|
||||
GET /datasets.json
|
||||
|
||||
All datasets are listed, including their core metadata. Additionally, certain
|
||||
parameters are given as facets (i.e. territories and languages of the
|
||||
datasets). Both ``territories`` and ``languages`` can also be passed in as
|
||||
query parameters to filter the result set. Supported formats are HTML, CSV and JSON.
|
||||
|
||||
"territories": [
|
||||
/* ... */
|
||||
{
|
||||
"count": 2,
|
||||
"url": "/datasets?territories=BH",
|
||||
"code": "BH",
|
||||
"label": "Bahrain"
|
||||
},
|
||||
/* ... */
|
||||
],
|
||||
"languages": /* Like territories. */
|
||||
"datasets": [
|
||||
{
|
||||
"name": "cra",
|
||||
"label": "Country Regional Analysis v2009",
|
||||
"description": "The Country Regional Analysis published by HM Treasury.",
|
||||
"currency": "GBP"
|
||||
},
|
||||
/* ... */
|
||||
]
|
||||
|
||||
#### Getting dataset metadata
|
||||
|
||||
GET /{dataset}.json
|
||||
|
||||
Core dataset metadata is returned. This call does not have any
|
||||
parameters. Supported formats are HTML and JSON.
|
||||
|
||||
{
|
||||
"name": "cra",
|
||||
"label": "Country Regional Analysis v2009",
|
||||
"description": "The Country Regional Analysis published by HM Treasury.",
|
||||
"currency": "GBP"
|
||||
}
|
||||
|
||||
Another call is available to get the full model description of
|
||||
the dataset in question, which includes the core metadata and also
|
||||
a full description of all dimensions, measures, and views. The
|
||||
format for this is always JSON::
|
||||
|
||||
GET /{dataset}/model.json
|
||||
|
||||
#### Listing dataset dimensions
|
||||
|
||||
GET /{dataset}/dimensions.json
|
||||
|
||||
A listing of dimensions, including type, description, and attribute
|
||||
definitions is returned. This call does not have any parameters.
|
||||
Supported formats are HTML and JSON.
|
||||
|
||||
[
|
||||
{
|
||||
"name": "from",
|
||||
"html_url": "http://openspending.org/ukgov-finances-cra/from",
|
||||
"label": "Paid from",
|
||||
"key": "from",
|
||||
"attributes": {
|
||||
"gov_department": {
|
||||
"column": null,
|
||||
"facet": false,
|
||||
"constant": "true",
|
||||
"datatype": "constant",
|
||||
"end_column": null
|
||||
},
|
||||
"name": {
|
||||
"column": "dept_code",
|
||||
"facet": false,
|
||||
"constant": null,
|
||||
"datatype": "string",
|
||||
"end_column": null
|
||||
},
|
||||
"label": {
|
||||
"column": "dept_name",
|
||||
"facet": false,
|
||||
"constant": null,
|
||||
"datatype": "string",
|
||||
"end_column": null
|
||||
}
|
||||
},
|
||||
"type": "compound",
|
||||
"description": "The entity that the money was paid from"
|
||||
},
|
||||
/* ... */
|
||||
]
|
||||
|
||||
#### Listing dimension members
|
||||
|
||||
GET /{dataset}/{dimension}.json
|
||||
|
||||
The returned JSON representation contains the dimension metadata,
|
||||
including type, label, description and attribute definitions.
|
||||
|
||||
{
|
||||
"name": "from",
|
||||
"html_url": "http://openspending.org/ukgov-finances-cra/from",
|
||||
"label": "Paid from",
|
||||
"key": "from",
|
||||
"attributes": {
|
||||
"gov_department": {
|
||||
"column": null,
|
||||
"facet": false,
|
||||
"constant": "true",
|
||||
"datatype": "constant",
|
||||
"end_column": null
|
||||
},
|
||||
"name": {
|
||||
"column": "dept_code",
|
||||
"facet": false,
|
||||
"constant": null,
|
||||
"datatype": "string",
|
||||
"end_column": null
|
||||
},
|
||||
"label": {
|
||||
"column": "dept_name",
|
||||
"facet": false,
|
||||
"constant": null,
|
||||
"datatype": "string",
|
||||
"end_column": null
|
||||
}
|
||||
},
|
||||
"type": "compound",
|
||||
"description": "The entity that the money was paid from"
|
||||
}
|
||||
|
||||
This call's return includes dimension metadata, but it may be too expensive
|
||||
to call for just this aspect.
|
||||
|
||||
#### Getting dimension members
|
||||
|
||||
GET /{dataset}/{dimension}/{name}.json
|
||||
|
||||
This will return the data stored on a given member ``name`` of the
|
||||
``dimension``, including its ``name``, ``label``, and any other
|
||||
defined attributes.
|
||||
|
||||
{
|
||||
"id": 2,
|
||||
"name": "10",
|
||||
"label": "Social protection",
|
||||
"description": "Government outlays on social protection ...",
|
||||
"level": "1"
|
||||
}
|
||||
|
||||
#### Listing entries in a dataset
|
||||
|
||||
Listing all the entries in a dataset (and offering export functionality)
|
||||
is handled by the full-text search. See [the search API](../search).
|
||||
|
||||
### Getting an entry
|
||||
|
||||
GET /{dataset}/entries/{id}.json
|
||||
|
||||
This will return a full representation of this entry, including all
|
||||
measures and all attributes of all dimensions. The entry ``id`` is a
|
||||
semi-natural key derived from dataset metadata which should be stable
|
||||
across several loads.
|
||||
|
||||
A CSV representation is available but will only have one row.
|
||||
|
||||
**Up**: [OpenSpending API](../)
|
||||
Reference in New Issue
Block a user