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: API concepts and management 2022

  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: API security 2022

  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: API development 2022

  Part C contains the technical details for API development, including general API implementation standards for API developers and consuming application developers.

Target audience

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.

Feedback welcomed

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 gcdo@dia.govt.nz.

Acknowledgements

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.

Related advice

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.

• Copyright and licensing (NZ-GOAL)
• Data
• Data and information management principles — Data.govt.nz
• Government enterprise architecture
• High-level advice about content reuse
• Open data charter
• Re-using Govt.nz content and data — Govt.nz