Skip to main content

Hypermedia implementation for Avocado

Project description

# Serrano

Serrano implements a hypermedia API for [Avocado](http://cbmi.github.com/avocado/). Avocado is a Django app which targets _developers who are interested in letting their data do the work for them_.

## Install

```bash
pip install serrano
```

## Configure

Include `serrano.urls` in your `ROOT_URLCONF` (the main **urls.py**):

```python
urlpatterns = patterns('',
...
url(r'^api/', include('serrano.urls')),
...
)
```

Add `django.contrib.sessions` to your project's `INSTALLED_APPS`:

```python
INSTALLED_APPS = (
...
'django.contrib.sessions',
)

```

Add the `serrano.middleware.SessionMiddleware` to the `MIDDLEWARE_CLASSES`
setting after Django's session and authentication middleware (if installed):

```python
MIDDLEWARE_CLASSES = (
...
'django.contrib.sessions.middleware.SessionMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'serrano.middleware.SessionMiddleware',
...
)

In this example, `/api/` is the root endpoint for Serrano. Hitting this endpoint will expose the available URLs for the API.

## Media Types

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._

### application/vnd.serrano.datacontext+json

#### Definition

A JSON-based media type representing a condition tree structure corresponding to Avocado's `DataContext` model.

#### Description

A tree structure with two types of nodes, **condition** and **branch**.

#### Node Types

##### Condition

```javascript
{
"id": <id>,
"operator": <operator>,
"value": <value>
}
```

#### Branch

```javascript
{
"type": <type>,
"children": [<node>, <node> [, ...]]
}
```

#### Node Elements

##### Condition Node

##### `id`
The value can be:

- An `int` representing the primary key identifer for a `DataField` instance, e.g. `1`
- Period-delimited `string` representing a natural key for a `DataField` instance, e.g. `'app.model.field'`
- An `array` of strings representing a natural key for a `DataField` instance, e.g. `["app", "model", "field"]`

##### `operator`
A `string` representing a valid `DataField` operator. Valid operators vary depending on the implementation, but should be validated downstream.

##### `value`
Any valid JSON data type.

##### Branch Node

##### `type`
A `string` that is `"and"` or `"or"` representing the type of branch or logical operation between child nodes defined in the `children` property.

##### `children`
An `array` of _two_ or more nodes.


#### Examples

##### Single Condition

```javascript
{
"id": 2,
"operator": "iexact",
"value": 50
}
```

##### Branch with Two Conditions

```javascript
{
"type": "and",
"children": [{
"id": 2,
"operator": "iexact",
"value": 50
}, {
"id": 1,
"operator": "in",
"value": ["foo", "bar"]
}
}
```

##### Branch with One Condition and One Branch

```javascript
{
"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"]
}]
}]
}
```

### application/vnd.serrano.dataview+json

#### Definition

A JSON-based media type representing an table-based output format corresponding to Avocado's `DataView` model.

#### Description

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`.

#### Example

```
{
"columns": [3, 1, 8],
"ordering": [[1, 'desc']],
}
```


## Resources

### DataField

Descriptive and other various metadata about `DataField` objects.

#### Schema

```javascript
{
"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/"
}
}
}
```

#### Endpoints

- `/api/fields/` - Array of `DataField` objects _(privileged users will also see unpublished
and archived data)_
- `/api/fields/:id/` - Single `DataField` object

#### Parameters

_sort_

- `category` _(default)_ - sort by the category (which is sorted by the order)
- `name` - sort by the name

_direction_

- `desc` _(default)_ - descending order
- `asc` - ascending order

_published (for privileged users)_

- `true` - filters the published objects
- `false` - filters the unpublished objects

_archived (for privileged users)_

- `true` - filters the archived objects
- `false` - filters the archived objects

_query_

- `<query term>` - Performs a robust search across metadata and the data values themselves

#### Links

- `stats` - 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 to

### DataField Values

Returns an array of distinct values for this `DataField`.

#### Schema

```javascript
[
{
"name": "Value 1",
"value": "value1"
},
...
]
```

#### Endpoints

- `/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.

#### Parameters

_query_

- `<query term>` - Performs a `LIKE` search on the values themselves

### DataField Stats

Various statistics about a particular `DataField`. The output of this is dependent on the data type.

### Schema

```javascript
{
"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/"
}
}
}
```

### Endpoints

- `/api/fields/:id/stats/` - Statistical data specific to the `DataField` object

#### Links

- `parent` - link to the corresponding `DataField` resource


### DataField Distribution

Dynamic resource for generating distribution data between one or more `DataField`s. This resource is only available if Numpy and SciPy has been installed as an optional dependency for Avocado.

#### Schema

```javascript
{
"clustered": true,
"data": [
{
"count": "Foo",
"values": [[...], ...]
},
...
],
"outliers": [
...
]
}
```

#### Endpoints

- `/api/fields/<pk>/dist/` - Defines a distribution between one or more `DataField`s

#### Parameters

_dimension_

- `<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 distribution
- `true` - 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 size
- `false` - Do not cluster



# Client Tools & Interfaces

Having a hypermedia API is great, but without a client to consume it, it is somewhat useless. [Cilantro](http://cbmi.github.com/cilantro/) is Web browser-based client that provides a clean browsable interface for viewing and interacting with the APIs Serrano provides.

Project details


Release history Release notifications

History Node

2.4.4

History Node

2.4.3

History Node

2.4.2

History Node

2.4.1

History Node

2.4.0.post1

History Node

2.3.14

History Node

2.3.13

History Node

2.3.12

History Node

2.3.11

History Node

2.3.10

History Node

2.3.9

History Node

2.3.8

History Node

2.3.7

History Node

2.3.6

History Node

2.3.5

History Node

2.3.4

History Node

2.3.3

History Node

2.3.2

History Node

2.3.1

History Node

2.3.0

History Node

2.2.0

History Node

2.1.5

History Node

2.1.4

History Node

2.1.3

History Node

2.1.2

History Node

2.1.1

History Node

2.1.0

History Node

2.0.18

History Node

2.0.17

History Node

2.0.16

History Node

2.0.15

History Node

2.0.14

History Node

2.0.13

History Node

2.0.12

History Node

2.0.11

History Node

2.0.10

History Node

2.0.9

History Node

2.0.8

History Node

2.0.7

History Node

2.0.6

History Node

2.0.5

History Node

2.0.4

History Node

2.0.3

History Node

2.0.2

History Node

2.0.1

This version
History Node

2.0

History Node

0.9.1b5

History Node

0.9.1b4

History Node

0.9.1b3

History Node

0.9.1b2

History Node

0.9.1b1

History Node

0.9b15

History Node

0.9b14

History Node

0.9b13

History Node

0.9b12

History Node

0.9b11

History Node

0.9b10

History Node

0.9b9

History Node

0.9b8

History Node

0.9b7

History Node

0.9b6

History Node

0.9b5

History Node

0.9b4

History Node

0.9b3

History Node

0.9b2

History Node

0.9b1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
serrano-2.0.tar.gz (15.0 kB) Copy SHA256 hash SHA256 Source None Oct 20, 2012

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page