Contact the Government Digital Service (GDS) to get a domain for your API on GOV.UK.

You can contact the Government Digital Service (GDS) to get a domain for your API on GOV.UK.

You should do this after ensuring your API meets the:

Contact GDS at [email protected] with the domain name you’d like.

This guidance only applies to api.gov.uk domains. If you need a non-API domain, for example to launch a new service, follow the guidance on getting a service domain name.

When choosing an API domain name

You should adopt name-of-the-apis.api.gov.uk as your subdomain naming convention, for example vehicle-registration-number.api.gov.uk. Consistent naming conventions make APIs and resources easier to locate.

The URL should be a suitable unique identifier for the specific API hosted on the domain. It should:

  • avoid reference to any current policy, scheme or organisation, as these may change in the future
  • be noun-based (rather than verb), and collection names should be plural nouns
  • be short, simple and clearly understandable – avoid technical or specialist terms where possible
  • follow versioning practices as outlined by the API Standards
  • follow GOV.UK policy on IDN domain names (they are currently not supported)

After contacting GDS with a domain name

Once you’ve agreed the name for your API, the GDS Reliability Engineering team will set up the domain and then delegate this to you. Your department will be responsible for choosing a DNS provider, managing the DNS servers provided, and procuring TLS certificates. Individual certificates are needed for each specific API domain, just as an individual certificate is required for each service.

GDS has set Domain-based Message Authentication, Reporting and Conformance (DMARC) and Sender Policy Framework (SPF) controls at the api.gov.uk level to cover your subdomain.

Securing your API domain

You must:

  • only advertise the base URL or docs URL of your GOV.UK API – it’s advised for security purposes not to advertise individual endpoints of your API, apart from in your documentation
  • enable HSTS for your entire subdomain (including the includeSubDomains flag) and add to the preload list (your API must never be provided over HTTP)
  • avoid sending emails from api.gov.uk subdomains (top-level SPF/DMARC rules are set to discard any that do get sent) and 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 in selecting your DNS provider and managing DNS entries

GDS is likely to set HSTS for the top-level api.gov.uk at some point in the near future. Users of the API domain will be informed when this happens.

After choosing your DNS provider

Your provider will give you several DNS name servers. As soon as you have these, send the details to [email protected] so GDS can request the delegation.

You’ll need to provide at least 2 nameserver records for your domain. GDS recommends you provide 4.

DNS is often a single point of failure. Consider using multiple suppliers so if one ever goes down, people will still be able to find your service.

You can search for DNS suppliers on the Digital Marketplace. If you don’t know which suppliers to choose, ask for advice from technical staff in your team or organisation.

Once you have a domain, you’ll need to make it clear to GDS who is responsible for the ownership of this domain in your organisation and keep this ownership up-to-date with GDS in case any issues arise.

Getting operations support

If you have an issue you can’t resolve with your DNS supplier, you can email the GOV.UK Reliability Engineering team at [email protected]. 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 (often referred to as ‘SPOC’) who will contact the support team for you.

If you later set up a developer hub

If you later choose to set up a developer hub, for instance to centralise access to technical and support documentation, or to provide associated API services like registration and key management, you can create redirects from your GOV.UK API subdomain that GDS has provided you with.

When naming your developer hub, it’s recommended to use the noun ‘developer’ in the URL before the name of your organisation. For example, ‘https://developer.organisationname.gov.uk’. There may be instances where you may choose to replace your organisation’s name in this example with your project’s remit. Contact GDS if you would like help to name your developer hub.

For 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. For example, your department could choose to create docs.name-of-the-apis.api.gov.uk after GDS has delegated your API subdomain.

Published 17 July 2019 Contents