General API Information

Schema

All API access is over HTTP.
Depending on your server you will access the following url :

API for Production : http://www.g8teway.com/api/v2/

and if you are on the Sandbox server : http://sandbox.g8teway.com/api/v2/

The Mobile Devices API is implemented as JSON over HTTP using all four verbs (GET/POST/ PUT/DELETE).

Being a RESTful API means that The Mobile Devices API uses standard HTTP requests, and follows a common convention for the various resources.

Each resource will typically have :

  • a GET request to list records (GET /messages),
  • a GET request to obtain a specific record (GET /messages/1).

POST requests are used to create new records (POST /messages).
You use PUT requests to update existing records (PUT /messages/1).

Finally, you can issue a DELETE request to destroy a resource (DELETE /messages/1).
(Please note that DELETING resources - except session - has been deactivated for safety reasons, a new soft-delete version, with time based expiration will be provided soon).

Every resource like Unit, Message, or Field, has their own URL and are manipulated in isolation through a REST API.

Authentication

You need to authenticate with a valid user before you can start using from the API. Authentication is done with the session resource, through a REST interface, thus using POST on /session to login and DELETE on /session to logout.

Example using the authentication through curl:

$ curl -F "username=your_user" -F "password=your_password" -F "client=your_client" \
  http://g8teway.com/api/v2/session.json -c mdi.cookie

or

$ curl -d "username=your_user&password=your_password&client=your_client" \
  'http://g8teway.com/api/v2/session.json' -c mdi.cookie
Once you’re authenticated, the server will provide with a cookie containing idenfication data that you’ll need to reuse for the next requests.

Cookie datas may change on each request, and it’s considered best practice to use a mechanism to store the cookie information between requests as browsers do.

Nevertheless, cookies provided by server are valid (and can be reused) for 1 hour.
Note that the expiration value is subject to change without notice, and you if you’re reusing cookie in an API client, you should pay special attention to catch expired session response from the server in order to relog.

Reading through the API

All read actions are done through GET, which means that they’re all easily explorable through a regular browser.

With the REST API, you’ll notice that every GET request on collections is paginated.

A “paginated collection” is a collection that will only return limit records, starting at record number start. These two parameters can be specified per-request. Note that the values of limit and start are caped by the server for to avoid ressource abuse.

Large collection can be retrieved piecemeal by changing the start parameter.

The policies used for limit and start parameters are described in this document for each api call.

Also note that the last element retrievable through pagination parameters will be the 200 000th.

A few examples of reading with curl:

$ curl 'http://g8teway.com/api/v2/units' -b mdi.cookie -c mdi.cookie
$ curl 'http://g8teway.com/api/v2/messages?units=1&format=json' -b mdi.cookie -c mdi.cookie

If the read is successful, you’ll get a JSON response back along with the status code “200 OK”.

Dealing with failure

If a request succeeds, it will return a status code in the 200 range and often, a formatted response. Note that, in general, if a request causes a new record to be created (like a new message, user), the response will use the “201 Created” status. Any other successful operation (like a successful query, delete, or update) will return a 200 status code.

If a request fails, a non-200 status code will be returned, possibly with error information as the response’s content. For instance, if a requested record could not be found, the HTTP response might look something like:

HTTP/1.1 404 Not Found
Date: Thu, 01 Mar 2009 17:41:40 GMT
...

Every client should be based on the HTTP status code only to detect the status of the request.

The Webservices also includes more verbose information about the error in the response body, but in a constant effort to be as specific as possible when displaying errors, this info is likely to change without notice between releases.
Response content should not be used to detect problems, but only for logging purpose when the HTTP Status is not 2XX.

Alternative formats

For each api call, the API is accepting a format parameter.
This parameter can now take the json and you can add _html at the end to have a pretty printed html output. For instance the json pretty printed format will be json_html. The API will automatically understand format passed as extension of the URL like messages.json_html.

A few examples of specifying format with curl:

$ curl 'http://g8teway.com/api/v2/messages.json' -b mdi.cookie -c mdi.cookie
$ curl 'http://g8teway.com/api/v2/messages.xml' -b mdi.cookie -c mdi.cookie
$ curl 'http://g8teway.com/api/v2/messages?format=json' -b mdi.cookie -c mdi.cookie

$ curl 'http://g8teway.com/api/v2/messages?format=json_html' -b mdi.cookie -c mdi.cookie
$ curl 'http://g8teway.com/api/v2/messages.json_html' -b mdi.cookie -c mdi.cookie

JSON callbacks

If you send a ‘callback’ variable to any call, it will wrap the result JSON in that function, so you can automatically execute it.

$ curl 'http://g8teway.com/api/v2/units?ret=id,modid&format=json&callback=myJsFunction' \
  -b mdi.cookie -c mdi.cookie

myJsFunction([
  {"unit": {"id": 42883, "modid": "mdi32180"}},
  {"unit": {"id": 42899, "modid": "mdi32161"}},
  // ...
  {"unit": {"id": 43043, "modid": "mdi32017"}},
  {"unit": {"id": 43045, "modid": "mdi32020"}}
]);

Limitations

Currently we are limiting API calls to 60 per minute. This may change in the future, or possibly per user at some point, but if you try to access the API more than 60 times in a minute, it will start giving you “access denied” errors.