API Guide

Developer Home API Guide

Sending a Request

The UKFast APIs are RESTful in nature and consumed over HTTPS. Each URL includes the services name, for example safedns and the version of the service you would like to use. The base URL for all requests to the UKFast API is https://api.ukfast.io.

An example CURL request to the UKFast API is shown below:

curl -H "Authorization: *API KEY*" \
    -X GET \
    "https://api.ukfast.io/safedns/v1/zones"

You can also use the Postman Client to help you test API responses, an example of this is shown below.

Authentication

Each API Application is tied to a specific company account and will only allow you to access / create resources under your own companies account. Contacts are not taken into account within the API, if you want to create more fine grained permissions within your application then this is your responsibility.

You are able to retrieve your API keys from the API Applications screen within MyUKFast. For more information about creating keys, take a look at the information here.

When making requests you should pass your API key in the Authorization header of the request.

HTTP Verbs

We use the following HTTP verbs within the UKFast API to specify what sort of action you would like to take with a resource:

The following verbs need a token with read access:

  • GET - Used to retrieve information for a resource

The following verbs need a token with write access:

  • POST - Used to create a new resource
  • PUT - Used to edit an existing resource
  • PATCH - Used to partially edit an existing resource
  • DELETE - Used to delete an existing resource

Filtering

Filtering allows you to search collections of data from the API. We have a selection of operators available following our GET parameter based syntax. To apply a filter to a field, you use the query parameter field:operator=value

For example, if you only want to return contacts whose first name is John, then you'd use ?name:eq=John

These operators combine to produce specific filtering. For example, you can use the gt and lt operators together to determine if one value falls between another: ?id:gt=10&id:lt=20

Operator Explanation Example
eq Checks that the field matches the given value ?name:eq=John
lk Performs a wildcard search on that field ?name:lk=j*
gt Checks that the field is greater than the given value ?id:gt=12
lt Checks that the field is less than the given value ?id:lt=12
in Checks that the field appears in a comma delimited list ?type:in=A,MX
neq Checks that the field does not match the given value ?name:neq=John
nin Checks that the field does not appear in a comma delimited list ?type:nin=A,MX
nlk Performs a negative wildcard search on that field ?name:nlk=j*

Sorting

It's also possible decide the sorting order for each field. The syntax is like the filtering syntax. You specify the sort query parameter, the field you want to sort and the direction. For example, if you wanted to sort by id descending, then you'd use sort=id:desc

You can also sort in ascending order using asc

Throttling

To ensure that the APIs are being used fairly and to stop consumers from affecting the performance of the API for other consumers, certain endpoints may be throttled. This limits the number of requests that the same IP address can send to the API in a specified amount of time.

Throttling is dependent on the API and if throttling is enabled for a API service, it will be specified in the relevant services documentation.

Versioning

You are able to specify the version of the API you want in the URL of the request. Each section of the API is versioned separately for maximum flexibility. For instance https://api.ukfast.io/safedns/v1/zones.

All our available APIs are currently using v1 only.

Status Codes

Each API response will have a corresponding HTTP status code. Generally speaking statuses in the 200 range indicate that the request was successful; 400-499 codes show a problem with the request and 500-599 codes indicate a server-side problem. We don't currently use status codes in the 300 range. More details of each of these status codes is shown below.

Status Code Meaning
200 OK Default status code for all responses
201 Created The resource that you specified has been created
202 Accepted The request meets validation rules and has been queued. Typically used for long running processes such as creating a server
400 Bad Request Generic client side error for when no other status code is appropriate
401 Unauthorized You have not specified your API key
402 Payment Required Your account does not currently have access to this feature (or adequate credit) to perform this action
403 Forbidden Your API key doesn't have access to the endpoint (either to this section of the API or using a read only key to try and make a write request)
404 Not Found The resource you are trying to access doesn't exist
405 Method Not Allowed You can't use that HTTP verb on this URL (other HTTP verbs may be allowed though)
408 Request Timeout The request has taken too long to process
410 Gone You are trying to access a resource that has been permanently deleted
422 Unprocessable Entity There are validation issues with the resource that you are trying to create or update
500 Internal Server Error An error has occurred that UKFast will have been notified about, please try again later
503 Service Unavailable The API is offline for maintenance, please try again later

Data Types

The data type for each attribute of a resource will be specified in the documentation for that endpoint. The following data types (or formats) are used within the API:

  • String
  • Integer: Used for any whole numbers
  • Float: Used for all other numbers
  • Boolean: Used for any value which can be represented with two states
  • Date: Will be returned in the format YYYY-MM-DD eg. 2018-08-23
  • DateTime: Will be returned in ISO-8601 format eg. 2017-08-01T13:27:56+00:00

Response Structure

Our API responses are designed to be consistent to make accessing them programmatically as easy as possible. You can see the different types of responses you might receive from the API along with an explanation of when each one is most likely to be used. Our interactive documentation for each endpoint will also show you the expected response type for that individual request.

Paginated Response

Paginated responses are used for returning collections of elements. The requested data is stored in the data property, and the metadata is stored in the meta property.

{
    "data": [
        {
            "name": "ukfast.co.uk",
            "description": "Main website"
        }
    ],
    "meta": {
        "pagination": {
            "total": 18,
            "count": 10,
            "per_page": 10,
            "total_pages": 2,
            "links": {
                "next": "https://api.ukfast.io/safedns/v1/zones?page=2",
                "first": "https://api.ukfast.io/safedns/v1/zones?page=1",
                "last": "https://api.ukfast.io/safedns/v1/zones?page=2"
            }
        }
    }
}

You can pass get parameters to customise the response. They are as follows:

Parameter Explanation Example Default
per_page Number of items to return per page 25 15
page Which page to jump to 3 1

The pagination metadata can be used to get more information on the returned collection. It also provides useful links to help traverse the paginated content. The following table outlines what each property indicates:

Property Explanation Example
total Total number of items for the entire collection. If you are filtering the collection, this only includes values that match the filter 212
count Number of items returned in this page 10
per_page Number of items requested for this page 20
total_pages Total number of pages 13
links.next Absolute URI to the next page https://api.ukfast.io/resource?page=3
links.previous Absolute URI to the previous page https://api.ukfast.io/resource?page=1
links.first Absolute URI to the first page https://api.ukfast.io/resource?page=1
links.last Absolute URI to the last page https://api.ukfast.io/resource?page=3

Each of the links properties will only be present if their value is possible. For example, if you are on the first page, then the next property won't be returned

Single Object Response

A single object response is just a standard JSON object of the requested resource nested within the data attribute. It's most commonly used for endpoints that get a single resource.

The object returned will be different depending on the endpoint. Each endpoint will have documentation detailing what object will be returned.

{
    "data": {
        "name": "ukfast.co.uk",
        "description": "Main website"
    },
    "meta": {
    }
}
Self Response

This is a response that links to the same resource you just interacted with. This is most often returned by endpoints where you create a resource, or update it.

{
    "data": {
        "id": 209685
    },
    "meta": {
        "location": "https://api.ukfast.io/pss/v1/requests/209685"
    }
}

The data property always contains the id of the newly created resource

The meta object always contains a location property which is an absolute path to an endpoint that gets information specific to that resource

No Content

This is a response that contains no content. This is typically only used for DELETE requests, where no useful information can be returned. The status code will be 204 in this scenario.

Errors

An error response is returned whenever something went wrong with the request, this can be due to authorization, validation, or server error.

An error object will always contain an errors property, which contains an array of error objects.

{
    "errors": [
        {
            "title": "Validation Error",
            "detail": "This name already exists",
            "status": 422,
            "source": "name"
        }
    ]
}

An error object contains:

Property Explanation Example
title A generic title or category for the error Not Found Error
detail More specific information on what went wrong with the request No zone with the id '20' found
status A HTTP status code specific to this error 404
source The property that's causing the error id