API design for public-sector integration

Reference article · 2 min read

An application programming interface is a contract between systems. In government, that contract may outlive the teams that wrote it and the vendors on either side. Designing it carefully pays off for years.

Principles

Resource-oriented. Model the things the agency cares about, such as parcels, permits, incidents, and accounts, as resources with stable identifiers.

Versioned. Changes that break existing clients go in a new version. Old versions are supported for a defined period.

Documented. A machine-readable specification, such as OpenAPI, plus written guidance. Generate documentation from the specification so it stays accurate.

Secure. Authentication for every call, authorization scoped to the client's need, encryption in transit, rate limiting, and audit logging.

Consistent. Common conventions for naming, pagination, filtering, errors, and dates across all of the agency's APIs.

Observable. Metrics and logs per client and per endpoint, so failures are diagnosed quickly.

Canonical data models

Systems disagree about what an address or a person looks like. Define a canonical model for shared concepts and translate to and from it at the edges. This prevents each new integration from inventing its own mapping.

Public APIs

Open data and public service APIs need additional care: clear terms of use, keys for identification, generous but enforced rate limits, and no personal data beyond what the corresponding open dataset would contain.

Vendor systems

Many commercial platforms provide APIs of varying quality. Contract language requiring documented, supported APIs with reasonable data access is the durable fix. Where an API is missing, file-based or database integration may be necessary, with monitoring to compensate.

Governance

An API catalog, an owner for each API, and a review step for new ones prevent sprawl. This is lightweight work that saves large amounts of confusion later.