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

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.

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.

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": 2,
            "count": 1,
            "per_page": 1,
            "total_pages": 2,
            "links": {
                "next": "https://api.ukfast.io/safedns/v1/zones?page=2",
                "previous": null,
                "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:

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:

Each of the links properties will be present even if their value isn't possible. For example, if you are on the final page, then the next property will be returned as null.

{
    "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: