DX, API Design & Documentation

API standardization in a Federated Landscape


Charles Baird is the Head of Data Architecture in the Data strategy and standards directorate in the Cabinet Office’s central digital and data office. The data Directorate is set up entirely to improve data sharing and management across the government. Their work is designed to help departments either share what they’re doing around best practices in data and architecture or learn from other departments effectively. This article by Charles is about API standardization in the federal landscape.

Our API program aims to help departments produce affordable, consistent, high-quality APIs for use across the government and beyond. There are some incredibly mature organizations across the government that have been doing excellent work with APIs for years. But our job is more about spreading that best practice and working as a center for enablement across government.

A lot of development is done by external contractors or suppliers when building APIs, and though they do good work, it requires some guidance and standards to help them develop consistently.

So, the two things that we are addressing are –

  • Discoverability
  • Quality Assurance


Many APIs have been generated in a government, but it’s really hard to find them. It is primarily because there’s no single central place where you can search for government APIs and no standardized way for departments to publish details of those APIs centrally. Many departments have repositories and catalogs, but there is no one place for all APIs.

We are trying to build a small and lightweight data discoverability standard that can be published from an internal catalog and consumed by either our central API catalog or another catalog. It’s less about building a big monolithic plus central platform and more about enabling a layer of discovery that sits on top of those catalogs.

Building manual catalogs will not serve the purpose of updating the catalogs will be a challenge. So, we need some catalogs that are programmatically connected. This is based on assumptions about what people seek and search for. Multiple vendors sell API platforms or data catalogs, which may not always suit your requirements. There could be security concerns.

Quality Assurance

Those APIs must be consistent and have high quality. Once users have found the API they need and arranged access to it, there are still delays to integration stemming from inconsistent interfaces because of a lack of standards in building them. This is not because of bad APIs but because of multiple teams, technologies, and approaches. To resolve this issue, we have built government API standards. We are building an API ruleset and adding some security checks. We show how code deviates from standards. We show warnings, vulnerabilities, etc.

At times, there is a pushback when we share standards and rules, but, especially in a situation where you’re brought in to develop an API for the government, you’re often quite grateful for tools that make that easier and standardize what you’re supposed to be delivered.

Way forward

As we move ahead, we will look towards –

More user testing – more testing by developers and architects

Ruleset expansion – Improving existing rules depending on the latest technologies and enhancements

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture