CDDO updates API guidance to make it more user-centric

The Central Digital and Data Office (CDDO), the Cabinet Office group leading the digital, data and technology (DDaT) function for government, has this week updated its guidance on documenting government APIs.

The Government Digital Service (GDS) first published its guidance to structuring, designing and publishing API documentation in early 2019. Since then, the responsibility for API standards and guidance has shifted to the CDDO. This is the first update since its publication.

An application programming interface, better known as API, is code that allows different software programmes to communicate with each other. APIs are essential to government digital services as they can connect siloed systems together. A catalogue of APIs published by public sector organisations in the UK is available through the GOV.UK website.

Documenting APIs helps developers and technical architects how to integrate them and connect government applications with users from other organisations.

What are the new updates?

Prior to the publication of the updates, the CDDO team reviewed the guidance with partners in government working in relevant areas, such as technical writing and API development.

The new version is designed to be clearer than its previous iteration and has fixed out-of-date links. It includes the following updates:

• A recommendation that team developers, user researchers and technical writers work together to plan, research and write API documentation
• A clearer outline of the ideas that CDDO recommends including in API documentation
• Detailed content in areas that previously lacked description, such as how to give a conceptual overview of how an API works
• A new style section encouraging use of plain language and tasks, rather than technology descriptions to help teams create user-centred documentation that goes beyond an API reference page or specification
• Links to the UK style guide and how to write about third-party products  
• Clarification on how and where to publish API documentation
• Signposting government teams to CDDO’s training to structure and write user-centred API documentation

A new iteration of the guidance is expected to be published once the CDDO receives feedback on this version.

(Photo: Arnold Francisca on Unsplash)