skip to navigation
skip to content

Not Logged In

serrano 2.0

Hypermedia implementation for Avocado

Latest Version: 2.3.4

# 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.
 
File Type Py Version Uploaded on Size
serrano-2.0.tar.gz (md5) Source 2012-10-20 14KB
  • Downloads (All Versions):
  • 129 downloads in the last day
  • 732 downloads in the last week
  • 4593 downloads in the last month