Overview

General points

All access is over HTTPS
Data is sent and received as JSON, exceptions are detailed in the endpoint reference
All timestamps are in ISO 8601 format

HTTP Verbs

Where possible we try to use appropriate HTTP verbs for each action.

Verb	Description
GET	For retrieving resources.
POST	For creating resources, usually against a collection resource, or for performing custom actions.
PUT	For replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE	For deleting resources.

Note that most resources support only a subset of these verbs, documented with the resource. A 405 ‘Method Not Implemented’ will be issued where appropriate.

Client Errors

Other possible types of client errors on API calls:

400 Bad Request

Sending malformed content, e.g. invalid JSON, in the body will result in a 400 Bad Request response.

401 Unauthorized

Invalid or missing authentication credentials see Authentication

403 Forbidden

The user does not have permission to perform the requested operation.

404 Not Found

The resource or one of its ‘owners’ as addressed in the URL does not exist will result in a 404 Not Found response.

422 Unprocessable Entity

Supplying invalid field values in the JSON body will result in a 422 Unprocessable Entity response.

    HTTP/1.1 422 Unprocessable Entity
    { "message":"Validation Failed",
      "errors": [
        { "resource":"User",
          "path":"/email",
          "code":"already_exists",
          "info":"A user already exists with that email address" }
      ]
    }

Error objects always have resource, path, and error code properties.

The path property is a JSON pointer referring to the offending property of the payload.
The code property is a reliable short code indicating the nature of the error

Possible validation error codes:

Error Code	Description
missing	A required field on a resource has not been set.
invalid	The formatting of a field is invalid, or some other constraint fails. The documentation for that resource should be able to give you more specific information.
already_exists	Another resource has the same value as this field. This can happen in resources that must have some unique key.

Sometimes there will be an info property with a human readable string with more information about the error and possible remediation actions.

If resources have custom validation codes, they will be documented with the resource.

Pagination and Sorting

Requests that return multiple items will be paginated to 100 items by default. Further pages can be requested with the page parameter. For some resources, you can also set a custom page size up to 1000 with the per_page parameter. Note that page numbering is 1-based and the default page is 1

GET https://api.tal.net/api/v1/applications?page=2&per_page=200

Most resource collections support sorting by datapaths using one or more occurences of the sort parameter, the syntax is <datapath>!(asc|desc) e.g.

GET https://api.tal.net/api/v1/applications?sort=application.user.lastname!asc&sort=application.main_process_state!desc

Gets all applications sorted first by applicant lastname descending then by status descending.

Link Header

The pagination info is included in the Link header. It is important to follow these Link header values instead of constructing your own URLs.

Link: <https://api.tal.net/api/v1/applications?page=2&per_page=200>; rel="next",
  <https://api.tal.net/api/v1/applications?page=6&per_page=200>; rel="last"

Possible rel values:

Name	Description
next	Immediate next page of results.
last	Last page of results.
first	First page of results.
prev	Immediate previous page of results.

Localisation

The language used for creation and serialisation of resources will usually be determined by the configuration of the API user and the system. If a different language is required then the Accept-Language header can be used to specify an alternative. If the requested Language is not supported then a 406 Not Acceptable response will be generated.