Hub API v1 Reference

Overview.md

API v1

• Schema
• Parameters
• Client Errors

Schema

All API access is over HTTP, and accessed from hub.lsts.pt/api/v1/. All data is sent and received as JSON.

$ curl -i http://hub.lsts.pt/api/v1/systems

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 12 Oct 2012 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate


[]

Blank fields are included as null instead of being omitted.

All timestamps must be used as UTC and in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ:

2012-10-09T23:39:01Z

All GPS Coordinates using WGS84 datum are returned in Decimal Degrees format and using GeoJSON syntax:

{
  "coordinates": [19.820664, -155.468066]
}

POST, PUT & PATCH bodies must be JSON encoded, Content-Type header must be application/json. A response status code 415 Unsupported Media Type will be throwed for a different content type.

With the exception for

• application/hub where specified in the endpoint documentation.

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the url can be passed as an HTTP query string parameter:

$ curl -i "http://hub.lsts.pt/api/v1/systems?gzip=true"

Client Errors

There are several possible types of client errors on API calls that receive request bodies:

Sending invalid JSON will result in a 400 Bad Request response.

 HTTP/1.1 400 Bad Request
 Content-Length: 35

 {"message":"Problems parsing JSON"}

Sending the wrong type of JSON values will result in a 400 Bad Request response.

 HTTP/1.1 400 Bad Request
 Content-Length: 40

 {"message":"Body should be a JSON Hash"}

Sending invalid fields will result in a 422 Unprocessable Entity response.

HTTP/1.1 422 Unprocessable Entity
 Content-Length: 149

 {
   "message": "Validation Failed",
   "errors": [
     {
       "key": "Error message",
       "name": "manta already exits",
       "example": "example error message"
     }
   ]
 }

Systems.md

Systems API

• List Systems
• List Active Systems
• Get a single system

List Systems

GET /systems

Response

Status: 200 OK
[
    {
        "imcid": 0,
        "name": "announce",
        "iridium": null,
        "created_at": "2013-07-02T01:56:04Z",
        "updated_at": "2013-07-02T01:56:04Z",
        "coordinates": [
            0,
            0
        ]
    },
    {
        "imcid": 1,
        "name": "isurus",
        "iridium": null,
        "created_at": "2013-07-02T01:56:04Z",
        "updated_at": "2013-07-02T01:56:04Z",
        "coordinates": [
            0,
            0
        ]
    }
]

List Active Systems

GET /systems/active

Note: This will return all the systems updated within 24hours and with GPS location available.

Response

Status: 200 OK
[
    {
        "imcid": 33796,
        "name": "spot-04",
        "iridium": null,
        "created_at": "2013-07-02T01:56:04Z",
        "updated_at": "2013-07-08T22:45:03Z",
        "coordinates": [
            41.17879,
            -8.5957
        ]
    },
    {
        "imcid": 33805,
        "name": "spot-13",
        "iridium": null,
        "created_at": "2013-07-02T01:56:04Z",
        "updated_at": "2013-07-08T22:45:03Z",
        "coordinates": [
            41.17862,
            -8.59545
        ]
    }
]

Get a single system

GET /systems/:imcid

Response

Status: 200 OK

{
    "imcid": 0,
    "name": "announce",
    "iridium": null,
    "created_at": "2013-07-02T01:56:04Z",
    "updated_at": "2013-07-02T01:56:04Z",
    "coordinates": [
        0,
        0
    ]
}