Skip to content
Alpha

This site is an alpha version and is still being developed in the open - your feedback will help us improve it. See the roadmap. Last updated: 14 October 2026.

Version in force: 0.3.0 (6 October 2026).

APIs and integration

How services talk to each other and to partners. Good integration lets us reuse capabilities and change one part of Defra without breaking another.

Doctrine: 4. Data is an enterprise asset, 6. Outcomes and services over organisational structures
Principles: 5. Connect and collaborate

Who these guardrails apply to

The core department. Whether the APIs and integration guardrails also apply to Defra's arm's length bodies is still to be confirmed.

Technology capability Enabling Platforms: aPI management and integration.

GR-API-01 API first

Should Design the API for a capability before (or with) the user interface, so other services and partners can use it.

Phases, evidence and status for GR-API-01
Status
Draft
Phases
Alpha, Beta
Led by
Technical architect
Evidence
API specification written before or alongside the user interface
Automated check
Manual
Maps to
Service Standard 13; Technology Code of Practice 9
DDTS doctrine
4, 6
Owner
Architecture team, last reviewed 2026-10-01, since v0.1.0

GR-API-02 Describe APIs with open specifications

Should Synchronous APIs are described with OpenAPI 3, and asynchronous/event interfaces with AsyncAPI, kept in the same repository as the code.

Why: Machine-readable contracts make APIs discoverable, testable and safe to change.

Phases, evidence and status for GR-API-02
Status
Draft
Phases
Alpha, Beta, Live
Led by
Developer
Evidence
  • Alpha: Draft OpenAPI 3 or AsyncAPI documents for the interfaces you are prototyping
  • Beta: OpenAPI 3 or AsyncAPI documents in the repository, checked in the pipeline against the running API
  • Live: Specifications kept in step with every released change
Automated check
Guardrail check (tools/guardrail-check): OpenAPI 3 and AsyncAPI documents present and well formed
Maps to
Service Standard 13; Technology Code of Practice 4, 9
DDTS doctrine
4, 6
Owner
Architecture team, last reviewed 2026-10-01, since v0.1.0

GR-API-03 Follow government API standards

Should Follow the API technical and data standards: RESTful resources, JSON, HTTPS only, consistent error formats and standard identifiers from the data standards.

Phases, evidence and status for GR-API-03
Status
Draft
Phases
Alpha, Beta, Live
Led by
Developer, Technical architect
Evidence
API design reviewed against the GDS API technical and data standards
Automated check
Manual
Maps to
Service Standard 13; Technology Code of Practice 4
DDTS doctrine
4, 6
Owner
Architecture team, last reviewed 2026-10-01, since v0.1.0

GR-API-04 Version and deprecate deliberately

Should Breaking changes are versioned, consumers are told in advance, and old versions have a published retirement date.

Phases, evidence and status for GR-API-04
Status
Draft
Phases
Beta, Live
Led by
Technical architect, Product manager
Evidence
  • Beta: Versioning approach published for each API and event
  • Live: Deprecation notices sent to consumers and retirement dates published for old versions
  • Significant change: Consumers told about breaking changes in advance, with a new version and a retirement date for the old one
  • Retire: Consumers told the retirement date in advance, and moved to a replacement
Automated check
Manual
Maps to
Technology Code of Practice 9
DDTS doctrine
4, 6
Owner
Architecture team, last reviewed 2026-10-01, since v0.1.0

GR-API-05 No integration through shared databases

Should Services do not read or write another service's database directly. Integrate through APIs, events or governed data products.

Why: Shared databases tightly couple services and make both impossible to change safely.

Phases, evidence and status for GR-API-05
Status
Draft
Phases
Alpha, Beta, Live
Led by
Technical architect
Evidence
  • Alpha: Container diagram showing integration only through APIs, events or governed data products
  • Beta: Built integrations match the container diagram, with no access to another service's database
  • Live: Integrations reviewed when the service or its dependencies change
Automated check
Manual
Maps to
Technology Code of Practice 9; Secure by Design principles 6
DDTS doctrine
4, 6
Owner
Architecture team, last reviewed 2026-10-01, since v0.1.0

GR-API-06 Use events for change notifications

Should Use asynchronous messages or events when other services need to react to something that happened (an application submitted, a permit issued), rather than polling.

Phases, evidence and status for GR-API-06
Status
Draft
Phases
Alpha, Beta
Led by
Technical architect, Developer
Evidence
Event and message definitions described in AsyncAPI
Automated check
Manual
DDTS doctrine
4, 6
Owner
Architecture team, last reviewed 2026-10-01, since v0.1.0

GR-API-07 Secure every API

Must All APIs authenticate callers (OAuth 2.0 / OpenID Connect or mutual TLS), authorise every request, validate input and apply rate limiting. No API is "internal so it's safe".

Phases, evidence and status for GR-API-07
Status
Draft
Phases
Alpha, Beta, Live
Led by
Security architect, Developer
Evidence
  • Alpha: Authentication, authorisation, input validation and rate limiting designed for each API
  • Beta: These controls built and covered by security testing
  • Live: API access reviewed, and controls re-tested after significant change
Automated check
Manual
Maps to
Service Standard 9; Technology Code of Practice 6; Secure by Design principles 7, 8
DDTS doctrine
4, 6
Owner
Architecture team, last reviewed 2026-10-01, since v0.1.0

GR-API-08 Make APIs discoverable

Should Register APIs in the platform API catalogue and, where they are useful beyond Defra, the government API catalogue.

Phases, evidence and status for GR-API-08
Status
Draft
Phases
Beta, Live
Led by
Technical architect
Evidence
Entry in the platform API catalogue
Automated check
Manual
Maps to
Technology Code of Practice 8
DDTS doctrine
4, 6
Owner
Architecture team, last reviewed 2026-10-01, since v0.1.0