API Protocol Reference

All API requests to IA are JSON requests sent to a single URL.

Each request contains authentication credentials, and an array of API actions. Each action will be executed in sequence, and the results returned.

The server response contains a success status, and (on success) the result of each action or (on failure) a description of the exception.

Responses also contain the current date and time on the API server, which you can store and use later in situations where you need to know the precise time when an API request occured. This represents the date/time when the server began processing the API request.

All requests must be sent over SSL/https, using the POST method, encoded in UTF-8.

Example API request

URL: https://admin.inspectionapps.com/services/api
Method: POST
Body:
{
  "username": "example-api-user",
  "password": "nkImwvt4yv0X3DLNh0ttwWDHgs8JSek",
  "actions": [
    {"name": "search", "params": {"entity": "job"}},
    {"name": "search", "params": {"entity": "inspection"}}
  ]
}

Example Response

{
  "success": true,
  "timestamp": "2013-04-12 10:32:12",
  "results": [
    {
      "entities": [
        {"idjob": 42, "address_one": "111 Mulgrave Rd", "city": "Cairns"...},
        {"idjob": 43, "address_one": "321 Shield St", "city": "Cairns" ...}
      ]
    },
    {
      "entities": [
        {"idinspection": 54, "idjob": 42, "idinspector": 123, "inspection_date": "2013-04-12 09:00:00", ...}
        {"idinspection": 55, "idjob": 43, "idinspector": 0, "inspection_date": "0000-00-00 00:00:00", ...}
       ]
     }
  ]
}

Exception Response

When an exception occurs, the server will usually respond with HTTP 500 and JSON describing the exception:

{
  "success": false,
  "timestamp": "2013-04-12 10:32:12",
  "error": "Invalid API username or password"
}

Not all exceptions can be caught properly. Always check if the response body is valid JSON, and if the "success" value is true. Any response with a JSON syntax error or non-true value is an exception.

If an exception occurs while processing an action, no further actions will be processed. In general the server only throws an exception when a completely invalid API request is received, incorrect auth credentials, or some kind of bug on the server.

Please report any exceptions you run into while using the API.

Deletion Policy

Data is rarely deleted from the database. Instead most records contain a "deleted" boolean which, if true, indicates that record should never be visible to the user.

Rows can be "deleted" by setting this value via an update operation.

When listing records without specifying a "modified since" search parameter, deleted rows are excluded from the result set to keep transfer sizes small. When you do specify a "modified since" search term, then any record deleted since that date will be returned indicating you must flag that row as deleted in your own copy of the database.

Further, when a database record is modified, the previous state of that database is usually also kept. These archive copies are not made available via the API but can be accessed if necessary.