OpenAPI 3.0 — The UK Standard for External APIs
FCA COBS disclosure: financial APIs must disclose what data they expose. An OpenAPI spec is a machine-readable disclosure document — FCA-inspectable.
NHS FHIR R4: NHS APIs use FHIR R4 which is a REST API standard — OpenAPI-documented FHIR capability statements are DTAC Domain 4 evidence.
G-Cloud service description: API capabilities described in OpenAPI format are accepted for G-Cloud technical documentation.
Automated testing: OpenAPI spec generates contract tests (Prism mock server, Dredd) — API behaviour validated against spec in CI/CD.
OpenAPI 3.0 (formerly Swagger) is the de-facto standard for documenting REST APIs. For UK regulated software, OpenAPI provides additional value beyond documentation:
UK GDPR and API Design — Practical Rules
UK GDPR Principle
API Design Requirement
Implementation
Data minimisation (Art 5(1)(c))
Return only fields necessary for the client's stated purpose
Field-level response schemas — no catch-all response objects
Purpose limitation (Art 5(1)(b))
Separate endpoints for separate purposes — no multipurpose dumps
Endpoint-per-use-case (not GET /user returning all data)
Storage limitation (Art 5(1)(e))
API responses should not encourage unnecessary data storage by client
Documentation: specify which response fields should not be cached
Security (Art 32)
API authentication and authorisation enforced at gateway
AWS API Gateway + Cognito JWT validation on every request
Data subject rights (Art 15–22)
APIs for DSAR fulfilment, erasure, portability
Dedicated endpoints: GET /data (DSAR), DELETE /account (erasure), GET /data.json (portability)
NHS FHIR R4 — REST API for HealthTech
Resource-based: FHIR resources (Patient, Observation, Appointment, MedicationRequest) are REST resources — GET /Patient/{id}, POST /Appointment.
UK Core profiles: NHS England's UK Core constrains FHIR R4 for UK use — specific code systems (SNOMED CT UK, dm+d, ODS codes).
DTAC Domain 4: HealthTech SaaS must provide a FHIR Capability Statement (/metadata endpoint) as interoperability evidence.
GraphQL is not NHS FHIR: attempting to implement NHS APIs with GraphQL instead of FHIR R4 REST fails DTAC Domain 4 requirements.
FHIR R4 (Fast Healthcare Interoperability Resources) is an NHS-mandated REST API standard for health data exchange. Key principles:
When GraphQL Is Genuinely the Right Choice
Dashboard with many data sources: a single GraphQL query can fetch data from multiple resolvers in one network round-trip — reduces dashboard load time.
Mobile applications with bandwidth constraints: request only the fields needed for the current view — reduces payload size.
Rapid product iteration: add new fields to schema without creating new endpoints — frontend teams move faster.
B2B developer portals: GitHub, Shopify, and Atlassian all use GraphQL for their developer APIs — complex, nested relationship data.
GraphQL solves the over-fetching and under-fetching problems of REST for complex frontend applications. Genuine GraphQL use cases: