Chiaro API

  1. Authentication and security
  2. HTTP verbs
  3. Requests
  4. Response formats
  5. Response headers
  6. Response examples

Authentication and security

All requests sent to the API must be sent over HTTPS and provide credentials for authentication. These credentials are a user and a 40 character key.

Use HTTP Basic authentication to send your user as the username and your key as the password.

To request credentials please contact us at api@chiaro.co.uk with an outline for the API access you require, if applicable.

If HTTP Basic authentication fails then you will receive an error and a 401 header response.

When accessing live resources you will also need to supply a token in the request header. Details for obtaining tokens will be provided when basic credentials are provided


HTTP verbs

The Chairo API is RESTful supporting the HTTP verbs GET, POST, PUT and DELETE:


Requests

GET

If an ID is sent in a GET request then a single record is returned, e.g.: /api/resources/333. To only return specific fields for a resource send the fields parameter with the request, e.g.: /api/resources/333?fields=id,name.

Otherwise a collection is returned, e.g.: /api/resources. Fields can also be specified for the collection. The collection is limited to 10 records by default. The collection size can be changed with the limit parameter, e.g.: /api/resources?limit=50. And to paginate use an offset, e.g.: /api/resources?limit=50&offset=50. If the collection should be ordered then send the order parameter, e.g.: /api/resources?order=updated+DESC.

POST

Creating a resource has no options, just send the data for the resource.

PUT

Updating a resource requires an ID to be sent in the request, as updating collections is usually not allowed. Just send the specific data to update for the individual resource.

DELETE

Deleting a resource also requires an ID to be sent in the request, as deleting collections is not allowed. No other data is required in the request.


Response formats

By default the format of responses from the API is JSON (Content-Type: application/json). If you do not specify a format then you will receive a JSON response.

Alternatively XML (Content-Type: application/xml) can be provided. You can specify the format by crafting the Accept header you send in your request or by appending the relevant file extension on the URI, ie: if the URI for the resource is /api/test then make it /api/test.xml to specify XML or /api/test.json to specify JSON. For single resources this would like /api/test/333.xml

In some cases it may be possible to request other formats like HTML or text. This is dependent on the API resources themselves. If other formats are available they will be listed on the documentation for the specific resource.


Response headers

The response headers are set according to the result of the request:

If the receiving application cannot handle the response headers with statuses other than 200 then each request must be appended with ?suppress_response_codes=true. This way the status code will always be 200, and the messaging will be the only indicator of the actual result.


Response examples

The response format is determined by the request's Accept header or alternatively by the file extension of the resource, as described above.

The response itself will contain the result of the request, as well as metadata and any errors encountered. The response for GET requests will contain the details of the request in the metadata, and errors as well as collections indexed by the collection name or single resources by the single resource name:

The examples below are given in JSON, though the same data is returned for XML. Where HTML or other unstructured formats are available then the data returned will be unstructured and contained within the result, or supplied directly depending on the request.

Single resource: /api/systems/1

{"result":
	{
	"system":
		{"id": 1, "name":"Chiaro", "email":"info@chiaro"},
	"_metadata":
		{"found":true}
	}
}

If the consuming application does not want the wrapping envelope then send an extra header No-Envelope set to true in the request. The result would then be like this:

{"system":
	{"id": 1, "name":"Chiaro", "email":"info@chiaro"}
}

If the consuming application does not want the item wrapped then send an extra header No-Item-Wrap set to true in the request. The result would then be like this:

{
	"id": 1, "name":"Chiaro", "email":"info@chiaro"
}

Single resource not found: /api/systems/12345

{"result":
    {
    "_metadata":
        {"found":false}
    "_errors":
        {"A resource 'system' with id '12345' does not exist"}
    }
}

Collection: /api/systems

{"result":
    {
    "systems": [
        {"system":
            {"id": 1, "name":"Chiaro", "email":"info@chiaro"}
        },
        {"system":
            {"id": 2, "name":"Elvie", "email":"info@elvie"}
        }]
    "_metadata":
        {"found":true}
    }
}

If the consuming application does not want the wrapping envelope then send an extra header No-Envelope set to true in the request. The result would then be like this:

{"systems": [
        {"system":
            {"id": 1, "name":"Chiaro", "email":"info@chiaro"},
        {"system":
            {"id": 2, "name":"Elvie", "email":"info@elvie"}
        }
    ]
}

If the consuming application does not want the item wrapped then send an extra header No-Item-Wrap set to true in the request. The result would then be like this:

{"systems": [
        {"id": 1, "name":"Chiaro", "email":"info@chiaro"},
        {"id": 2, "name":"Elvie", "email":"info@elvie"}
    ]
}

Collection ordered, limited and specific fields: /api/systems?limit=200&order=name&fields=name,email

{"result":
    {
    "systems": [
        {"system":
            {"name":"Chiaro", "email":"info@chiaro"}
        },
        {"system":
            {"name":"Elvie", "email":"info@elvie"}
        }],
    "_metadata":
        {"found":true, "requested_limit":200, "limit":100,"order":"name", "fields":"name,email"},
    "_errors":
        {"limit":"The maximum limit is '100'"}
    }
}

Collection filtered: /api/systems?limit=1&filter=email+%3D+info%40chiaro

The filter is constructed using the field name to filter on, the operator and the value to use to filter. Multiple filters can be provided by sending an array of filters (filter[]=...&filter[]=...etc.).

Allowed operators are: =, !=, <>, >, >=, <, <=, LIKE, IS

The filter should be URL encoded.

{"result":
    {
    "systems": [
        {"system":
            {"name":"Chiaro", "email":"info@chiaro"}
        },
     ],
    "_metadata":
        {"found":true, "requested_limit":1, "limit":1, "fields":"*"},
    }
}