Learn about how government agencies are implementing APIs to their systems and what the benefits are of doing this.
The API guidelines 2022 provide government agencies context for API standards, focused design and implementation guidance, and API best practices. This is intended to help agencies achieve a consistent and common approach to developing and delivering APIs.
The API guidelines 2022
The guidelines are split into the following 3 parts:
Part A contains the business context for APIs within government. It describes the principles and considerations that creating APIs could impact an agency, across government and public services, and commercial innovation. This replaces the version published in 2016 called API standard and guidelines — Part A: Business.
Part B contains the API security reference architecture and technical details for implementing API security. This replaces the 2016 version called API standard and guidelines — Part B: Technical, which has been split into 2 parts for the 2022 version — Part B: API security and Part C: API development.
Part C contains the technical details for API development, including general API implementation standards for API developers and consuming application developers.
Note: These guidelines:
- are intended to apply for all API standards and protocols, however much of the guidance is oriented to REST (Representative State Transfer) APIs
- use hypothetical or actual use cases with a government context to illustrate practical application of the concepts described. Examples do not represent recommended API design and / or data content requirements for the NZ government.
Part A: API concepts and management
The target audience for part A is primarily technical business people who need to understand the value and benefit of APIs and gain an appreciation of what is involved and needs to be in place.
Part A also provides the context for parts B and C for enterprise architects, solution architects and API developers in agencies.
It may be of interest to commercial entities, non-governmental organisations (NGOs) or other third parties who are developing, or planning to develop, applications that use government APIs.
Part B: API security and Part C: API development
The target audience for parts B and C is primarily solution designers and API developers in agencies and organisations within the public service.
Additionally, compliance and assurance personnel may be interested in terms of assessing alignment with the standards and guidelines.
Application of the guidelines
The main reason for these guidelines is to give agencies and vendors some common, default guidance on API implementation to help accelerate the development of government APIs.
Therefore, most of the specific technical guidance is marked as ‘recommended’ rather than mandatory. Exceptions tend to be in areas of security, authorisation and referenced standards compliance.
It is recognised that many sectors or industries will have existing APIs and associated standards, which may be established and governed outside an agency’s control. In such cases, industry standards will prevail, but agencies are encouraged to review their existing use of APIs against these guidelines and consider whether any discrepancies reflect material business risks.
Agencies that have their own existing APIs will also need to balance the risk and cost of the change against the benefits of conforming with these guidelines — a phased approach may be appropriate.
Agencies are asked to provide feedback on these updated guidelines, about their usability, effectiveness and any areas of ambiguity, to the Agency Standards and Integration team at firstname.lastname@example.org.
The API guidelines were initially commissioned and endorsed jointly by the Government Enterprise Architecture Group and the ICT Partnership Framework Technology Working Group in 2016.
In 2022, these guidelines were updated to reflect current API practice.
Te Tari Taiwhenua Department of Internal Affairs would like to thank the many agency representatives and Middleware NZ who helped to produce these guidelines.
One of the key drivers of APIs is to unlock government data sources, so APIs need to be as easy as possible for developers to discover, understand and develop against. They need to be simple to understand and well described.