Guidance

Get an API domain on GOV.UK

Contact the Central Digital and Data Office (CDDO) to get a domain for your API on GOV.UK.

• From: Central Digital and Data Office
• Published: 17 July 2019
• Last updated: 19 January 2021 — See all updates

You can contact the Central Digital and Data Office (CDDO) to get a domain for your API on GOV.UK.

You should only apply for an API domain after making sure your API meets the government’s API technical and data standards. If there are reasons for your API not meeting particular standards, you’ll need to discuss this with CDDO as part of your application.

Before you apply

You must appoint a domain name administrator to register and manage the domain. They will be responsible for:

• choosing a Domain Name Service (DNS) provider - you can search for DNS providers on the Digital Marketplace and read our guidance on choosing a good DNS provider
• managing the DNS servers
• managing Transport Layer Security (TLS) certificates for each API domain

Your domain name administrator must have the authority to apply for a .api.gov.uk domain name on behalf of your organisation. Read the guidance on getting written permission for more information.

You must use a role-based email address in a public sector domain like ‘servicedesk@example.gov.uk’. Do not use an individual’s email address.

CDDO will need to be able to contact your domain name administrator, so you must keep this contact up to date. Make sure to regularly check that the email address is still active, and let CDDO know if any contact details change.

Choosing a domain name

Each API you run should have its own domain name. Your domain name must be clear and descriptive so it’s easier for users to find and use your API and resources.

Your domain name should:

• be between 3 and 63 characters long
• contain only alphanumeric characters (0-9 and a-z) and the ‘-’ (dash) symbol
• use dashes between words to make your domain easy to read - for example, vehicle-registration-number.api.gov.uk
• use nouns rather than verbs, for example driving-licence-renewal.api.gov.uk rather than renew-driving-licence.api.gov.uk
• be short, simple and easy to understand - try to avoid technical or specialist terms
• not include the name of a policy, scheme or organisation, to avoid having to change it later

Apply for your domain

1. Request the API domain from CDDO

Your domain name administrator will need to contact CDDO at api-domain-request@digital.cabinet-office.gov.uk with:

• your chosen domain name
• a role-based email address and phone number
• written permission from your organisation showing authorisation to apply for the domain name

CDDO will contact you to confirm that you’ll:

• be running a single API off your domain
• follow the versioning practices and other standards set out in the API technical and data standards

CDDO will contact you to confirm the status of your application.

2. Set up and activate your API domain

Your DNS provider will have given you several DNS name server (NS) records. After CDDO has approved your domain, send your NS records to api-domain-request@digital.cabinet-office.gov.uk so CDDO can delegate the domain.

You must send at least 2 NS records for your domain, but you should send more if you can. Providing multiple NS records means that if one goes down, the DNS can look at the next one on the list.

You must also add your API to the government’s API Catalogue to help users find your API and show that your API meets government standards.

3. Secure your API and domain

You will need to keep your API and its domain name secure. You must:

• use TLS v1.2 or above - do not use Secure Sockets Layer (SSL) or older versions of TLS
• use HTTPS, not HTTP - this will secure connections to your API, preserve user privacy, ensure data integrity and authenticate the server providing the API
• avoid sending emails from .api.gov.uk subdomains - CDDO has set top-level SPF and DMARC rules to discard any that do get sent
• follow guidance on keeping your domain protected from spoofing attacks
• use a Certification Authority Authorisation (CAA) record on your .api.gov.uk domain - this stops attackers from getting another certificate authority to issue a certificate for the domain
• comply with the Minimum Cyber Security Standard when managing your DNS entries

If you’re hosting documentation or any other browser-based content, you must enable HTTP Strict Transport Security (HSTS) for your entire subdomain, including the includeSubDomains flag.

You can find out more about keeping your domain name secure.

4. Manage your API and domain

Keep CDDO updated about any changes to the management or ownership of the domain by emailing api-domain-request@digital.cabinet-office.gov.uk.

You must decommission your API and domain name when they are no longer needed, for example if the service they support shuts down.

When decommissioning your API domain, make sure you:

• give users of your APIs enough notice to update their service
• contact CDDO to decommission your API domain name
• update your API documentation to say when you’re deprecating and retiring the API - you can also put a deprecation notice in your HTTP headers

Hosting your API documentation

It’s best practice to keep your API documentation on the same domain as your API as they are part of the same product.

CDDO recommends publishing your documentation as a subdirectory of your domain, for example at name-of-api.api.gov.uk/docs. Using subdirectories means it’s easier to structure and version your documentation. Use consistent naming convention for your documentation across all your published APIs.

Keep your documentation up to date with the correct endpoint URLs, and make sure the API Catalogue lists the correct URL to your documentation.

Getting operations support

If you have an issue you cannot resolve with your DNS supplier, you can email the GOV.UK team at hostmaster@digital.cabinet-office.gov.uk. The team is available on weekdays between 9am and 5pm.

If you have an emergency outside of these hours, you must contact your organisation’s single point of contact (SPOC) who will contact the support team for you.

Published 17 July 2019
Last updated 19 January 2021 + show all updates

1. 19 January 2021

   Added a section "Before you apply" with requirements on appointing a domain name administrator and using a public sector role-based email. The “Apply for your domain” section is now split into 'steps'. There is now a requirement to provide written permission showing the authority to apply for an API domain and a note that API domains must be published to the API Catalogue. Security criteria now includes requirements to use TLS and HTTPS, and a redundant point about advertising individual endpoints was removed. Guidance has been added on decommissioning API domains when the API is no longer in use. The Documentation section recommends subdirectories (/docs) as opposed to subdomains (docs.). Anything not specifically relevant to getting an API domain, such as guidance on service domains and developer hubs, has been removed.

2. 17 July 2019

   First published.