REST APIs

This guide provides details about the conventions followed by our REST APIs.

API Versions

Our APIs are released using the semantic versioning conventions. Minor and patch releases will always be backwards compatible. Each time a major version is released, it is included in the URI /v2/orders/1234. You may continue to use the previous version of the URI, however it will be deprecated and will be removed in a future release.

HTTP Verbs

Method	Success Status	Query String	Request Body	Idempotent	State Changing	Response	Description
GET	200					The requested resources(s)	Used to retrieve a resource
POST	201, 202					Location header containing URI for newly created resource, body containing the created resource response (201 only)	Used to create a resource.
PUT	204, 202					No body	Used to update an entire resource.
PATCH	204, 202					No body	Used to update a part of a resource.
DELETE	202, 204					No body	Used to delete a resource.
OPTIONS	200					No body	Returns the available HTTP method for the requested resource URI in the Accept response header
HEAD	-	-	-	-	-	-	Not currently supported
TRACE	-	-	-	-	-	-	Disallowed.
TRACK	-	-	-	-	-	-	Disallowed.

Content Types

Most RESTful APIs support JSON. Please refer to the API specific documentation for any alternative or additional content types.

The content types your client accepts should be expressed in the Accept header, for example:

Accept: application/json

The content type of the response will match your Accept. If you include more than one content type, the API will select based on its own precedence. Please refer to the API documentation. If the API does not support content type(s) that you included in the Accept header, you will receive an HTTP 415 error response.

Status Codes

The following table shows the status codes that are used

Status Code	Supported Methods	Usage
200 OK	GET	Used for successful requests
201 Created	POST	Used exclusively for POST requests, to confirm successful resource creation
202 Accepted	POST, PUT, PATCH, DELETE	Used for requests that have passed validation, but will be processed asynchronously
204 No Content	PUT, PATCH, DELETE	Used for synchronous requests, which return no response body content
304 Not Modified	GET	Used to indicate a resource is the same as when it was last queried. Only used when clients include If-None-Match or Modified-Since request headers.
400 Bad Request	GET, POST, PUT, PATCH, DELETE	One or more query string parameters (GET request) was not supplied when required, or was not valid. The request body (POST/PUT/PATCH) was not supplied, was missing a mandatory value or was not valid. See error responses.
401 Unauthorized	Any	Invalid or no JWT token supplied
403 Forbidden	Any	Authenticated, but not authorised to perform the operation
404 Not Found	GET, POST, PUT, PATCH, DELETE	The requested resource does not exist
405 Method Not Allowed	Any	Always used for HEAD, TRACE and TRACK. Used by GET/POST/PUT/PATCH/DELETE if the request resource does not support them
406 Not Acceptable	GET	The client does accept the content type of the resource
413Payload Too Large	POST, PUT, PATCH	Used only during bulk requests. Indicates that the request body is too large (either in bytes or number of permitted items within the bulk operation)
415 Unsupported Media Type	POST, PUT, PATCH	The client has sent a request body with a content type not supported by the server
429 Too Many Requests	GET, POST, PUT, PATCH, DELETE	Used when throttling limit is reached
500 Internal Server Error	GET, POST, PUT, PATCH, DELETE	An error occurred whilst processing the request. This status may result from bad input from the client, which in turn is the result of insufficient validation of that input, as validation errors should be 400.
503 Service Unavailable	GET, POST, PUT, PATCH, DELETE	Service not available. Used during an outage.

Error Responses

An error response that was caused by invalid input will be indicated by a 400 response.

The body of the response will contain a representation of the error details. For example:

{"message":"Unable to parse JSON"}

An error response will always include a message. In the event that the error was caused by a validation error, resulting from invalid input, the fields in error will be expressed in the following way:

{
  "message": "Validation Failed",
  "errors": [
    {
      "field": "companyName",
      "code": "missingField"
    },
    {
      "field": "emailAddress",
      "code": "invalid",
      "message": "not a well-formed email address"
   },
   {
      "field": "device.model",
      "code": "invalid",
      "message": "not valid polycom model"
      "reference": "https://developers.gamma.co.uk/docs/horizon/errors#1234"
  }
 ]
}

Some more specific validation errors may include a reference which describes the input requirements in more details.

Paging

Endpoints which return large volumes of data may include a paging option that allows the request to specify a subset of data that is to be returned. If an endpoint supports paging, it will be specified in the endpoint documentation. This subset is specified by the page and perPage query string parameters.

The following request limits the total number of records to be returned:

GET https://api.gamma.co.uk/example/list?perPage=10

The response will include the following headers:

Link: <https://api.gamma.co.uk/example/list?perPage=10&page=2>; rel="next", <https://api.gamma.co.uk/example/list?perPage=10&page=20>; rel="last"
X-Pagination-Total-Pages: 10
X-Pagination-Total-Count: 100
X-Pagination-Current-Page: 2
X-Pagination-Page-Size: 10

The Link header provides URIs for the first, previous, next and last pages. Some may be omitted depending on the current page, for example the previous and first page URIs will not be included if the current page is page 1.

The X-Pagination headers provide additional meta data about the total pages, total number of records, current page and page size.

Endpoints which support paging will include a default number of records per page. This is specified in the individual endpoint documentation. Endpoints may also specify a maximum number of records per page. A request which includes a perPage parameter which exceeds the maximum will result in an error 400.

Some endpoints may not be able to supply the total number of records or pages. In this scenario the X-Pagination-Total-Pages and X-Pagination-Total-Count headers will be omitted in the response. The Link header will include only a URI for next if more records are available.

Sorting

Endpoints which return collections of data (for example a list of CLIs) may include a sorting option that allows items in the collection to be sorted. If an endpoint supports sorting, it will be specified in the endpoint documentation.

Sorting is applied by supplying the sort query string parameter. For example:

GET https://api.gamma.co.uk/example/list?sort=name,-date

The above example will sort first by name ascending, and then by date descending. Unless the endpoint documentation describes otherwise, all fields that would be returned by the response for the endpoint are available for sorting. Endpoint documentation will list fields available for sorting if only a subset are supported. A request which includes a field in the sort parameter which is not supported will result in an error 400.

Hypermedia

Hypermedia as the Engine of Application State is not implemented fully. Our APIs do not include links, aside from those used in paging responses as described above.

Resources, and where applicable nested resources, do however include a self URI. For example:

{
   "id": 1234,
   "self": "https://api.gamma.co.uk/horizon/v1/orders/1234",
   "company": {
      "id": 1234,
      "self": "https://api.gamma.co.uk/horizon/v1/companies/1234",
   },
   "cpe": [
     {
        "model":"Polycom"
     }
   ]
}

A self URI is included only if the resource, or nested resource, is individually accessible.

Field Limiting

Some endpoints will return a great many fields in their responses. You may not need every field to be returned. Consequently, some endpoints will support field limiting, which allows a request to specify the fields that should be included in the response using the fields query string parameter.

For example, a request sent to https://api.gamma.co.uk/inbound/v1/numbers/1234 could return:

{
  "id":1234
  "cli": "+44123456789",
  "self": "https://api.gamma.co.uk/inbound/v1/clis/1234"
  "status": "active",
  "callPlan" : {
    "id":1234,
    "self": "https://api.gamma.co.uk/inbound/v1/clis/1234/callplan"
    "name": "My callplan"
  }
}

Specifying the fields to include, for example https://api.gamma.co.uk/inbound/v1/numbers/1234?fields=cli,status will reduce the fields included in the response:

{
  "id":1234
  "cli": "+44123456789",
  "self": "https://api.gamma.co.uk/inbound/v1/clis/1234"
  "status": "active"
}

The id and self fields are always included.

Expanding Fields

Some endpoints will support expanding fields. Endpoints which return a large amount of nested resources will sometimes not return these resources in full, only the id and self will be returned. The endpoint documentation will describe if this is the case.

In these scenarios, a request may specify that the entire nested resource is to be expanded, so all of its fields are returned.

For example a request sent to https://api.gamma.co.uk/inbound/v1/numbers/1234 could return:

{
  "id":1234
  "cli": "+44123456789",
  "self": "https://api.gamma.co.uk/inbound/v1/clis/1234"
  "status": "active",
  "callPlan" : {
    "id":1234,
    "self": "https://api.gamma.co.uk/inbound/v1/clis/1234/callplan"
  }
}

Specifying the fields to exapanded, for example https://api.gamma.co.uk/inbound/v1/numbers/1234?expand=callPlan will include the full set of fields from the nested resource:

{
  "id":1234
  "cli": "+44123456789",
  "self": "https://api.gamma.co.uk/inbound/v1/clis/1234"
  "status": "active",
  "callPlan" : {
    "id":1234,
    "self": "https://api.gamma.co.uk/inbound/v1/clis/1234/callplan"
    "name": "My callplan",
    "lastUpdated": "2018-02-02T11:06:08Z",
    "destination": "+44123456789"
 }
}