GPS Data Web Service API

Conventions

Additional Type Hinting

The data objects hold additional clues about the nature of their contents, expressed in the object's property names.

Factory URLs

When creating new data objects, a POST request is performed at a so-called "factory URL". Usually, a URL at which you can retrieve a list of data objects is also a factory URL.

As an example, you can get a list of all your zones by making a GET request on gateway.zones_url. Making a POST request (containing, in this case, a data object that looks like a zone) will create a new zone data object.

Persistent URL Parameters

All URL parameters that begin with an underscore are persisted across links that are returned from the web service. If you add any of them to a request once, the value will be in any URLs that you follow. This allows a small bit of state to be carried across requests.

_format
Our service can return XML, JSON or HTML at the same URL, deciding the content type based on the standard HTTP Accept header. If, however, it is simpler for your programming model to tack on a URL parameter rather than using HTTP headers, this parameter has the highest priority in deciding the content type to return.
_tz
This string indicates which Time Zone should be used when making requests that involve dividing data by day. Because your data is stored in a format independent of time zones, it can be viewed according to any of the supported time zones dynamically.
_token
The authentication string generated by our server that you can use to authenticate requests. This is the only parameter that is not persisted if your client sends the "token" cookie. (see Authenticating your HTTP requests)

Data Object Naming

The data object descriptions use the following convention:

non_editable
This is a non-editable property of an object. You can read to your heart's content, but it will be ignored completely if you try to update it.
editable
This is an editable property of the object. You can update it when you GET the resource, make changes to the property (see Data Formats), and PUT the changed resource back to the URL you got it from.
related_url
This is a link that you can follow to some other data object. You know this because of type hinting. By the way: all "url" or "*_url" parameters are relative to the URL at which you retrieved this data object. So, you will have to resolve the URL.
list_of_data
This is an array of objects, and each object has the format described below:
item_url
A link to another resource, often the URL to access this "child object" directly (e.g., not as a member of the list).
some_prop
A property of this object, non-editable
other_prop
An editable property of the object. To make a change, you'll have to call HTTP PUT at the URL of this object (possibly item_url).
note
Sometimes not all information about an object is included when it is given as a list embedded in another object. In that case, there may be more information about the object when you GET it at its address (item_url).