Design-First vs Code-First — UK Comparison
| Approach | How It Works | UK Advantages | UK Disadvantages |
|---|---|---|---|
| Design-first (API-first) | Write OpenAPI spec → generate server stubs → implement logic | FCA COBS disclosure ready from Day 1, contract tests possible, parallel frontend/backend | Additional upfront time (1–2 days) |
| Code-first | Write code → generate OpenAPI from annotations | Faster initial start | OpenAPI quality varies — may not satisfy FCA/GDS requirements |
| ClickMasters approach | Design-first on all UK projects | FCA, NHS, GDS compliance built into API design, not retrofitted | — |
OpenAPI 3.0 — UK Regulatory Value
| Regulation | OpenAPI Value | How ClickMasters Implements |
|---|---|---|
| FCA COBS 4 (financial promotions) | Machine-readable API disclosure — inspector-auditable | OpenAPI spec version-controlled in Git, published at /api-docs |
| NHS DTAC Domain 4 (interoperability) | FHIR Capability Statement = OpenAPI equivalent | ClickMasters publishes FHIR CapabilityStatement (/metadata) + OpenAPI for non-FHIR APIs |
| GDS Service Standard | API documentation must enable reuse by other services | OpenAPI spec published as part of GDS technical documentation |
| ICO API transparency | Article 13/14 UK GDPR: data subjects informed what APIs exist that process their data | API inventory (from OpenAPI specs) fed into ROPA and privacy notice |
| PCI-DSS SAQ-A | API boundary scope reduction — payment card data never in API | OpenAPI spec shows payment endpoints use Stripe Elements redirect (no card data in spec) |
API Versioning — UK Best Practice
| Strategy | How It Works | UK Compliance Implications | ClickMasters Recommendation |
|---|---|---|---|
| URL versioning (/v1/, /v2/) | New major version = new URL path | ✅ FCA: version in URL is auditable in access logs | ✅ Standard for all external UK APIs |
| Header versioning | API-Version: 2 header | Harder to audit in URL logs — FCA prefers URL | Not recommended for FCA-regulated APIs |
| No versioning (schema evolution) | Only additive changes allowed ever | Constrains product evolution — avoid for APIs | Not recommended for external APIs |
| Date-based (/2024-01-01/) | Stripe-style date versioning | Clean audit trail | For high-volume public APIs only |
Contract Testing for UK APIs
NHS FHIR R4: FHIR provider contract tests verify UK Core profile compliance on every CI/CD run — breaking FHIR changes caught before deployment.
FCA Open Banking: consumer-driven contract tests verify OBIE-standard API compliance — prevents breaking changes to payment APIs.
GOV.UK API: contract tests verify GOV.UK Notify integration, GOV.UK Pay integration, and Companies House API continue to behave as expected.
Multi-team development: contract tests allow frontend and backend teams to develop independently — the contract (OpenAPI spec) is the integration agreement.
Contract testing verifies that API consumers (frontend, mobile apps, third-party integrations) and API providers (backend services) agree on the API contract. Particularly important for: