home api list

Hexostore API Documentation

Making Requests

All requests are conducted over SSL. Any non-SSL requests received are forwarded to HTTPS. All requests must be authenticated with OAuth2 with the exception of createuserrequest.

Currently, only JSON is supported except for the data endpoint which supports a few other formats. Please specify an Accept and Content-Type header accordingly.

On the whole, interactions with the API behave as described in Tastypie's documentation. A couple of notable restrictions are:

DELETE and PUT requests to list views are always denied.
PUT to a detail view of a non-existant instance will not attempt to create the instance, it will result in a 404.
POST requests to detail views are always denied.

Otherwise, things should work more-or-less as expected.

Retrieving Biometric Data

To retrieve biometric data (heartrate, ptt, etc.), use the data call or the endpoint that corresponds with the datatype you wish to query. All biometric data endpoints work the same way and are desribed in the data documentation.

All other resources (user, record, range, etc) work as described in the following section.

Retrieving Resources

Lists

To get a list of resources, you make a GET request to the resource's endpoint. For instance, to retrieve all the datatypes you would make the following request:

curl -i https://api.hexoskin.com/api/datatype/

Note that the resource name is singular and there is a trailing slash.

Requests to lists return an object containing two members; meta containing information about the results and objects which are a list of the results. A sample result from /api/datatype/?offset=20:

{
    "meta": {
        "limit": 20,
        "next": "/api/datatype/?limit=20&offset=40",
        "offset": 20,
        "previous": "/api/datatype/?limit=20&offset=0",
        "total_count": 54
    },
    "objects": [
        {
            "dataid": 208,
            "freq": null,
            "info": "Recorder start annotation.",
            "name": "RECSTR_ANNOT_CHAR",
            "resource_uri": "/api/datatype/208/"
        },
        {
            "dataid": 209,
            "freq": null,
            "info": "Recorder stop annotation.",
            "name": "RECSTP_ANNOT_CHAR",
            "resource_uri": "/api/datatype/209/"
        },
        ...
    ]
}

As you can see, the meta object tells us how to page through the data. You can roll your own paging routines of course, but you may also use the next and previous attributes of the meta object. The limit and offset variables are passed in the GET to determine which page to retrieve.

Filtering and Ordering

Variables for filtering and ordering the results are also passed through the GET arguments. You can filter on any combination of fields and filter types in the Filtering Options of a resource. Refer to the 'Filtering Options' section of endpoint's documentation to determine what these are for that resource. For example, records support the following filtering options:

device
    exact, in

start
    exact, range, gt, gte, lt, lte

end
    exact, range, gt, gte, lt, lte

user
    exact, in

You use a filter type by passing a GET argument of [column]__[filtertype]=[value]. So to view a list of records that contains only records that started on or after a startTimestamp of 347631277170, you would append startTimestamp__gte=347631277170 to the URL. Like this:

https://api.hexoskin.com/api/record/?startTimestamp__gte=347631277170

If no filtertype is specified, exact is assumed. so user__exact=/api/user/99 is the same as user=/api/user/99.

Ordering works in a similar fashion. Columns which support ordering are listed in each endpoints' documentation under 'Sorting Options'. You may pass order_by= followed by a comma-separated list of columns. The sort order is ascending by default, to make the sort order descending prepend the column name with a -. So to add a descending order to our record query, you would make the following request:

https://api.hexoskin.com/api/record/?startTimestamp__gte=347631277170&order_by=-startTimestamp

Loading a Specific Resource Instance

To load a specific instance of a resource, you access the resource_uri directly. So to access the Recorder start annotation datatype directly, you would make a GET request to:

https://api.hexoskin.com/api/datatype/208/

In this case there is no object containing meta and objects attributes, rather the resource instance is returned directly.

{
    "dataid": 208,
    "freq": null,
    "info": "Recorder start annotation.",
    "name": "RECSTR_ANNOT_CHAR",
    "resource_uri": "/api/datatype/208/"
}

Creating

Creating an instance of a resource is achieved by issuing a POST or a PATCH request to the list view of the desired resource. If the instance is created is successfully, you will receive a 201 with the location of the new resource in the Location header. For many resources, the instance will be in the body but sometimes, primarily in cases where there is a lot of data involved, the instance representation is omitted.

Not all resources support PATCH requests and some don't support creation at all! Please refer to the documentation for each resource to see what methods are supported and which fields must be supplied.

Updating

To update an instance, you may send a PUT or a PATCH to the URI of the resource instance you wish to update. As with creation, support for different methods vary between resources, be sure to check the docs.

If you use the PATCH method, it is not necessary to supply the entire object, you may supply only the fields you wish to change. If you use the PUT method you must provide a complete object to replace the existing one.

Deleting

Deleting, as one would expect, is done by sending a DELETE request to the resource instance's URI.

Cached Content

The API caches results to improve performance. If your are receiving a cached response, the X-HexoCache header will be present and will contain a timestamp (normal timestamp, not a HexoTimestamp) of the time it was cached.

Error Codes

400 Bad Request

There is a problem with the data or the format of the data supplied.

401 Unauthorized

Your authentication failed.

403 Forbidden

Your user is not allowed to do what your are trying to do.

404 Not Found

The resource does not exist or you are not allowed to see the resource instance requested.

405 Method Not Allowed

You have attempted to use a method which is not allowed on the given resource.

500 Server Error

The API has encountered an error.