Guide to our approach to the retirement of API endpoints

This guide documents our approach to the retirement of API endpoints and what users can expect when an endpoint is going to be retired.

Why are endpoints retired?

Endpoints, systems or features can be phased out or retired due to:

  • legislative changes
  • replacement technology
  • lack of users
  • costs of upkeep
  • other business reasons

“Sunsetting” occurs at the end of the product life cycle and is the period of time when a product is planned to be retired, but is still live and in use. A product or service is only sunset when there is a formal agreement, target date agreed for when a service will be decommissioned and these have been communicated to our users, teams and stakeholders.

Timeline of the end of life process

  1. Formal agreement is put in place internally that an API is due to reach its end of life and should be sunsetted
  2. Migration guide and/or blog post detailing sunset and retirement published
  3. Sunset headers are put on API endpoints that are affected
  4. End of life date is reached
  5. Rolling blackouts can be used to determine if any further users are impacted
  6. API endpoint is retired

When an endpoint is retired, 404 error codes will be received by clients still querying the endpoint. In addition to this, during a rolling blackout, the sunset headers will still be issued in order to provide further information to users.

At each stage through this process we will review any feedback collected through our Feedback Service that may impact the decision to proceed with the the next stage.

How will users know an endpoint is being sunsetted?

In the response headers to clients, we will issue three additional headers when an endpoint is scheduled to be removed:

  • Deprecation (the date the decision was taken to deprecate this endpoint)
  • Link (a link where you can find more information)
  • Sunset (the date of when this service will cease to return data on its endpoints and instead return blanket 404 status codes)

For example:

Deprecation: Thu, 7 Mar 2024 09:00:00 GMT
Link: https://developer.ons.gov.uk/retirement
Sunset: Wed, 11 May 2024 23:59:59 GMT

What can users do when their endpoint is being sunsetted?

For any API endpoint that is being sunsetted, we will provide a migration guide to using new services if there is one available.

If this is not sufficient, users can provide feedback via our Feedback Service which we will review at the end of every stage of the timeline before progressing to the next stage.

What endpoints are currently reaching end of life?

Data endpoints for aggregated search pages

It has been decided that ONS will retire the data endpoints for our aggregated search pages due to the following reasons:

  • out of date technology
  • built as a proof of concept
  • strategic technology direction is elsewhere
  • cost of upkeep is too high with similar services available

The UI for these pages has already been moved to use our Search API and it is the intention of ONS to separate data and UI endpoints by domain in future. Data in JSON format will be accessible via our API found at https://api.beta.ons.gov.uk/v1/search

The endpoints to be decommissioned will be:

  • /alladhocs/data
  • /allmethodologies/data
  • */datalist/data
  • */publications/data
  • /publishedrequests/data
  • */staticlist/data
  • /timeseriestool/data
  • */topicspecificmethodology/data
  • /releasecalendar/data

Items marked with a * can appear at any url path on the ONS website, with the others only appearing at the root level.

These are for the following domains:

  • ons.gov.uk

To migrate to one of our new services, please read our migration guide.

v0 API

It has been decided that ONS will retire our ‘v0 API’ due to the following reasons:

  • out of date technology
  • built as a proof of concept
  • strategic technology direction is elsewhere
  • cost of upkeep is too high with similar services available

This application provides the following API endpoints:

  • /dataset
  • /dataset/{dataset_id}
  • /dataset/{dataset_id}/timeseries
  • /dataset/{dataset_id}/timeseries/{timeseries_id}
  • /dataset/{dataset_id}/timeseries/{timeseries_id}/data
  • /timeseries
  • /timeseries/{timeseries_id}/dataset
  • /search

These are for the following domains:

  • api.beta.ons.gov.uk
  • api.ons.gov.uk

To migrate to one of our new services, please read our migration guide.

Data endpoints for content pages

It has been decided that ONS will retire the data endpoints for our content pages due to the following reasons:

  • lack of clear and obvious need for content pages to be consumed in this way
  • cost of upkeep

This update will only impact those endpoints that do not pertain to the timeseries or dataset content types.

The specific types of pages affected are:

Label Content Type
Article article
Article Download article_download
Bulletin bulletin
Chart chart
Compendium Chapter compendium_chapter
Compendium Data compendium_data
Compendium Landing Page compendium_landing_page
Equation equation
Home Page home_page
Home Page Census home_page_census
Image image
Product Page product_page
Reference Tables reference_tables
Release release
Static Adhoc static_adhoc
Static Article static_article
Static FOI static_foi
Static Landing Page static_landing_page
Static Methodology static_methodology
Static Methodology Download static_methodology_download
Static Page static_page
Static QMI static_qmi
Table table
Taxonomy Landing Page taxonomy_landing_page
Visualisation visualisation

The following types of pages are not affected:

Label Content Type
API Dataset api_dataset
API Dataset Landing Page api_dataset_landing_page
Dataset dataset
Dataset Landing Page dataset_landing_page
Data Slice data_slice
Timeseries timeseries
Timeseries Dataset timeseries_dataset
Timeseries Landing Page timeseries_landing_page