Hypermedia API for Avocado
This project is maintained by cbmi
Serrano implements a hypermedia API for Avocado. Avocado is a Django app which targets developers who are interested in letting their data do the work for them.
pip install serrano
Include serrano.urls in your ROOT_URLCONF (the main urls.py):
urlpatterns = patterns('',
...
url(r'^api/', include('serrano.urls')),
...
)
Add django.contrib.sessions to your project's INSTALLED_APPS:
INSTALLED_APPS = (
...
'django.contrib.sessions',
)
In this example, /api/ is the root endpoint for Serrano. Hitting this endpoint will expose the available URLs for the API.
Serrano is a Hypermedia API implementation for Avocado. Defined here are the media types Serrano uses to represent data structures corresponding to those in Avocado.
Note that currently Serrano exposed plain application/json representations of the below mediatypes.
A JSON-based media type representing a condition tree structure corresponding to Avocado's DataContext model.
A tree structure with two types of nodes, condition and branch.
{
"id": <id>,
"operator": <operator>,
"value": <value>
}
{
"type": <type>,
"children": [<node>, <node> [, ...]]
}
idThe value can be:
int representing the primary key identifer for a DataField instance, e.g. 1
string representing a natural key for a DataField instance, e.g. 'app.model.field'
array of strings representing a natural key for a DataField instance, e.g. ["app", "model", "field"]
operatorA string representing a valid DataField operator. Valid operators vary depending on the implementation, but should be validated downstream.
valueAny valid JSON data type.
typeA string that is "and" or "or" representing the type of branch or logical operation between child nodes defined in the children property.
childrenAn array of two or more nodes.
{
"id": 2,
"operator": "iexact",
"value": 50
}
{
"type": "and",
"children": [{
"id": 2,
"operator": "iexact",
"value": 50
}, {
"id": 1,
"operator": "in",
"value": ["foo", "bar"]
}
}
{
"type": "or",
"children": [{
"id": 2,
"operator": "iexact",
"value": 50
}, {
"type": "and",
"children": [{
"id": 1,
"operator": "in",
"value": ["foo", "bar"]
}, {
"id": 1,
"operator": "in",
"value": ["baz", "qux"]
}]
}]
}
A JSON-based media type representing an table-based output format corresponding to Avocado's DataView model.
Contains two properties columns and ordering which represent the selected output columns for the table and column ordering, respectively. Each column in this context corresponds to a DataConcept.
{
"columns": [3, 1, 8],
"ordering": [[1, 'desc']],
}
Descriptive and other various metadata about DataField objects.
{
"id": 4,
"name": "Ethnicity",
"name_plural": "Ethnicities",
"description": "The fact or state of belonging to a social group that has a common national or cultural tradition",
"keywords": "",
"unit": null,
"unit_plural": null,
"category" : {
"id": 2,
"name": "Demographics",
"order": 1,
"parent_id": null
},
"app_name": "patient",
"model_name": "demographics",
"field_name": "ethnicity",
"modified": "2012-02-04T15:11:03Z",
"created": "2012-02-04T15:11:03Z",
"published": true,
"archived": false,
"simple_type": "string",
"internal_type": "char",
"enumerable": true,
"data_modified": "2011-10-01T11:05:10Z",
"links": {
"self": {
"rel": "self",
"href": "http://example.com/api/fields/1/",
},
"values": {
"rel": "data",
"href": "http://example.com/api/fields/1/values/"
},
"stats": {
"rel": "data",
"href": "http://example.com/api/fields/1/stats/"
},
"distribution": {
"rel": "data",
"href": "http://example.com/api/fields/1/distribution/"
},
"concepts": {
"rel": "related",
"href": "http://example.com/api/fields/1/concepts/"
}
}
}
/api/fields/ - Array of DataField objects (privileged users will also see unpublished
and archived data)
/api/fields/:id/ - Single DataField objectsort
category (default) - sort by the category (which is sorted by the order)name - sort by the namedirection
desc (default) - descending orderasc - ascending orderpublished (for privileged users)
true - filters the published objectsfalse - filters the unpublished objectsarchived (for privileged users)
true - filters the archived objectsfalse - filters the archived objectsquery
<query term> - Performs a robust search across metadata and the data values themselvesstats - link to aggregation data about the DataField
distribution - link to distribution data for the DataField
concepts - link to DataConcept objects in which this DataField is related toReturns an array of distinct values for this DataField.
[
{
"name": "Value 1",
"value": "value1"
},
...
]
/api/fields/:id/values/ - Unique values for a DataField.Note: This endpoint may be used when a datafield is flagged as searchable and can same a query parameter q for performing searches on the values themselves.
A convention for better search implementations is to override the URL to point to a different resource which supports the same media types.
query
<query term> - Performs a LIKE search on the values themselvesVarious statistics about a particular DataField. The output of this is dependent on the data type.
{
"size": null,
"count": null,
"max": null,
"min": null,
"avg": null,
"sum": null,
"stddev": null,
"variance": null,
"links": {
"parent": {
"rel": "parent",
"href": "http://example.com/api/fields/1/"
}
}
}
/api/fields/:id/stats/ - Statistical data specific to the DataField objectparent - link to the corresponding DataField resourceDynamic resource for generating distribution data between one or more DataFields. This resource is only available if Numpy and SciPy has been installed as an optional dependency for Avocado.
{
"clustered": true,
"data": [
{
"count": "Foo",
"values": [[...], ...]
},
...
],
"outliers": [
...
]
}
/api/fields/<pk>/dist/ - Defines a distribution between one or more DataFieldsdimension
<pk> - Add a dimension to the distribution. Multiple dimensions can be provided using multiple GET parameters, e.g. /api/fields/3/distribution/?dimension=4&dimension=6
nulls
false (default) - Exclude NULL values from distributiontrue - Include NULL values in distribution. Note, for continuous data that is clustered, nulls are removed.cluster
null (default) - If the vector size exceeds this threshold, the data is down-sampled to a more reasonable size based on the current size of the data. Note, this sampling is now an approximation of the data and information is lost.true - Explicitly cluster the distribution regardless of the sizefalse - Do not clusterHaving a hypermedia API is great, but without a client to consume it, it is somewhat useless. Cilantro is Web browser-based client that provides a clean browsable interface for viewing and interacting with the APIs Serrano provides.