Public Service API Standards: A Practical Guide Beyond the Checklist

Two public bodies want to share data. Connecting their systems should take a few weeks. It often takes months, because the two were built to different conventions for structuring a request, returning an error, and authenticating a caller. Engineers spend weeks reconciling those differences before any data moves.

In November 2025, the Data Governance Unit in the Office of the Government Chief Information Officer (OGCIO) published the Public Service API Standards and Guidelines to address this. The guidelines acknowledge the problem in plain terms, noting that APIs have been “developed organically across government departments”. They replace the OGCIO guidelines from 2021 and apply to any public service API that shares data, “regardless of sharing being permitted by the DSGA or not”. If your organisation shares data over an API, they apply to you.

Most of the guidelines set out technical conventions you apply and follow. How to name a resource, which HTTP method to use, how to format a date

A smaller number involve design decisions that are expensive to reverse once the API is live. When one goes wrong, the organisations consuming the API usually pay for it, even though the provider made the choice. Four of these are worth examining.

The guidelines state that developing an API is “similar to the development of a product”. A product has an owner who stays responsible after it launches. That person answers when a consuming body reports a fault, and approves any change that affects other consumers. Assigning that owner is an organisational question the guidelines cannot answer for you.

Many public bodies never assign it. The API ships, the project team moves on, and when something fails in production no one is responsible for responding.

The guidelines require every API to be versioned, so a consumer can tell when something has changed. A bug fix or a backward-compatible addition can ship with little fuss. A change that breaks how consumers already use the API needs as much notice as you can give, and at least six months where they have not agreed to move faster.

The guidelines warn that an API which keeps functioning while distorting its data over time “can also be catastrophic”. The requests still return a success code, the values it returns are wrong, and the fault spreads to every consumer before anyone detects it.

A breaking change that takes the provider an afternoon forces every consuming body to:

• rewrite its integration code,
• fit the work into a release cycle it had already planned, and
• retest against dependencies it may not control.

A change that takes you an hour can take a dozen consumers a fortnight each.

So track who consumes your API and keep a way to reach them. The six-month notice period is worth nothing if no one is responsible for issuing it.

Pagination and filtering have to be designed into the API before it is built. Pagination returns a large result set in pages rather than all at once.

An endpoint without it returns everything in a single response. That works at launch, when the table holds 200 rows. As the table grows to 200,000, every call slows down, and the consumers notice before the provider does.

Adding pagination later changes the shape of the response, which breaks every client already reading the old one. That makes it a breaking change, with the same six-month notice period as the section above. Filtering, which lets a consumer ask for a subset instead of the whole collection, has to be planned in for the same reason.

The guidelines require every error response to carry a human-readable message and an application-specific error code, on top of the HTTP status. What you want is an error response the consuming organisation can diagnose on its own, without access to your server logs.

A bare HTTP 500 falls short of that. It can mean a dozen different things, and telling them apart needs server logs the consumer cannot see, so the integration sits broken while two teams investigate from opposite ends. An error code that names the fault, and a message that says how to fix it, let the consumer resolve it without contacting you.

Design error responses with the same care as successful ones, and test what happens when they fail as thoroughly. Teams routinely leave error handling until last, then learn in production how much it matters.

The remaining sections are best followed as written. Two points are worth taking from them.

• Security: The requirements are not equally urgent. For any API handling personal data, start with TLS, which encrypts data in transit, and a token-based authentication method such as OAuth 2.0. Keep API keys in the request headers. Put them in the URL or query string and they get written into server logs and browser history, where others can read them.
• Testing: Load testing, checking the API under heavy traffic, is the step most often skipped. An API that passes one developer’s tests can fail the first time several departments query it at once. Test it for more traffic than you expect.

The API standards cover the technical side of sharing data. They do not address who owns a dataset, or whether two bodies use the same definition for the same field. Those questions belong to the Data Sharing Standards Framework, published alongside the API standards in November.

You need both, and you need them together. Build the API before agreeing who owns the data and what its fields mean, and the API will faithfully move data that means one thing in the first body and something else in the second.

If you are scoping a data-sharing project, writing a procurement specification, or reviewing APIs you already operate, we are happy to talk through what the standards mean for your organisation.