Government API Catalogue: Disclosure Requirements (Traceable Draft)
This document provides a list of information that agencies should disclose about their APIs when listing them in a government API catalogue. Every field included has a valid, traceable citation to the authoritative NZ API Guidelines.
Core Catalogue Purpose
The API catalogue lists the APIs offered, along with their interface specification and guidance on how to gain access and use the APIs (DocRef).
The catalogue information needs to be up to date and accurate in order to be relied upon by API application developers (DocRef).
1. API Identification and Provider Information
| Field |
Justification |
Citation |
| API Provider |
"The organisation that provides the API to expose a resource (information or functionality) for consumers" |
Part A Glossary |
| Interface Specification |
"Provides technical information to the application developer community about the API. It includes information about how the API works, any access control features and any error conditions" |
Part A Glossary |
| Resource Description |
"The information or functionality exposed by the API" — developers focus "primarily on the resource they wish to access, rather than the government agency providing the resource" |
Part A 3.5 |
2. API Classification
| Field |
Justification |
Citation |
| Exposure Level (Internal / External / Partner / Public) |
APIs are "commonly categorised" by exposure: Internal API, External API, Partner API, Public/Open API |
Part A 1.2 Table 1 |
| API Category (System / Process / Experience) |
Three categories for governance: System APIs, Process APIs, Experience APIs — with different frequency of change, effort, impact, and ownership |
Part A 3.2 |
| API Type (REST / GraphQL / AsyncAPI / gRPC) |
"There are several different types of API and the type you choose may depend on the technical use cases" — REST, GraphQL, AsyncAPI, gRPC |
Part C 1.2 |
3. Technical Specification
| Field |
Justification |
Citation |
| Machine-Readable Specification |
"Interface specifications SHOULD also be provided in a machine-readable format" — OpenAPI (REST), AsyncAPI (event-driven), GraphQL Schema, Protocol Buffers (gRPC) |
Part A 3.1.2 |
| Specification Format |
Machine-readable formats include: "OpenAPI Specification for REST APIs, AsyncAPI for event-driven APIs, GraphQL Schema for GraphQL APIs, Protocol Buffers for gRPC APIs" |
NZ API Standard Draft |
| Current Version |
"APIs should have a clear indication of the version so that application developers can ensure they are using the appropriate version" |
Part C 1.5 |
4. Access Control Information
| Field |
Justification |
Citation |
| Granularity of Access Control |
The catalogue should include "guidance on how to gain access and use the APIs, including the granularity of access control" |
Part A 4.2 |
| Authentication Method |
"Authentication is required to identify the consumers and/or consuming applications that want to access or consume an API" — options include API Keys, OAuth 2.0, OpenID Connect, Certificates |
Part B 3.1 |
| API Keys |
"API keys are recommended as they provide a level of security to public APIs that can help protect sites from screen scraping or provide the required information to throttle, or possibly bill, access to data" |
Part B 7.3 |
| TLS Version |
"All communications to or from an API MUST be over TLS 1.3 or higher" |
Part B 11.1 |
5. Developer Portal Capabilities
The API developer portal SHOULD offer (DocRef):
| Field |
Justification |
Citation |
| Discovery |
"Making it simple for developers to find APIs that match their need" |
Part A 5.1.1 |
| Onboarding / Registration |
"Allowing developers to register and sign-up for API usage plans with support for automatic approval or manual approval workflows" |
Part A 5.1.1 |
| Education / Documentation |
"Providing developers with the information they need to make use of APIs" |
Part A 5.1.1 |
| Code Examples |
"Offering example code and sample applications to illustrate the functionality of the API" |
Part A 5.1.1 |
| API Evaluation / Sandbox |
"Giving developers a 'sandpit' capability to try the APIs interactively" |
Part A 5.1.1 |
| Community / Forums |
"Enabling developers to share knowledge, experience and best practices via a support community such as online forums" |
Part A 5.1.1 |
| Usage Metrics |
"Delivering insight into API usage and performance that could be useful to developers" |
Part A 5.1.1 |
| SLA Publication |
"A place to publish API SLAs, defining performance, availability metrics" |
Part A 5.1.1 |
6. Service Level Information
| Field |
Justification |
Citation |
| Service Level Agreement (SLA) |
"APIs often require service level agreements (SLAs) with application developers and suppliers. SLAs are important to understand and will likely evolve over time as the API matures" |
Part A 1.9 |
| Performance Metrics |
SLAs SHOULD define: "Response time thresholds, Throughput guarantees, Transaction speed requirements" |
NZ API Standard Draft |
| Availability Metrics |
SLAs SHOULD define: "Uptime percentage (e.g., 99.9%), Scheduled maintenance windows, Maximum downtime per period" |
NZ API Standard Draft |
| Throttling / Rate Limits |
"API management looks after availability of the API. This can involve throttling to make sure all consumers can get access to the API within the bounds of the SLA" |
Part A 4.3 |
| Quota Management |
"Quota management, whereby consuming applications are given limited access (for example, a set number of calls per hour) to protect the API from abuse or overuse" |
Part A 4.3 |
| API Longevity |
"Application developers (especially commercial entities) will need to know how long the API will exist, what commitment there is to its availability and performance, and what support is offered" |
Part A 4.1.2 |
7. Lifecycle and Versioning
| Field |
Justification |
Citation |
| Lifecycle Stage |
"Life cycle management means managing the full life cycle of APIs from initial publication to destruction" — stages include Service Strategy, Service Design, Service Transition, Service Operation, Continual Service Improvement |
Part A 5.1 |
| Version Number |
"The URI SHOULD include /vN with the major version (N) and v as a prefix" |
Part C 1.5 |
| Deprecation Notice |
Deprecation process SHOULD include: "Notify all consumers — Provide advance notice with sufficient lead time" and "Set retirement date — Only after majority of consumers have transitioned" |
NZ API Standard Draft |
| Roadmap |
"This SHOULD include roadmaps to indicate the planned evolution of an API so that developers are pre-warned and have time to prepare for changes" |
Part A 4.1.1 |
| Breaking Changes |
"A breaking change SHOULD be considered as a major version change" — "For major changes which are not backwards compatible, the old API version SHOULD be maintained alongside the new version" |
Part C 1.10, Part A 2.6 |
8. Consumer Management
| Field |
Justification |
Citation |
| Consumer Registration |
"The ability of knowing who is using an API cannot be overstated. This is critical when it comes time to implement aspects of the API service life cycle, such as service deprecation, or notification of an outage" |
Part B 3.1 |
| Consumer Identification |
"It is important that all application developers are identified, even if the API is considered public" |
Part A 2.8 |
9. API Portal Functions
From Part B Table 2 — Core components (DocRef):
| Field |
Justification |
Citation |
| Discovery of APIs |
API portal provides "discovery of APIs" |
Part B 1.4 Table 2 |
| Analytics |
API portal provides "analytics to monitor APIs" |
Part B 1.4 Table 2 |
| Specifications and Descriptions |
API portal provides "access to specifications and descriptions of APIs, including Service Level Agreements (SLAs)" |
Part B 1.4 Table 2 |
Summary: Required Disclosure Fields
Based on the traceable citations above, the following fields have explicit support in the NZ API Guidelines:
MUST Disclose (Mandatory)
- Interface Specification — machine-readable format
- TLS Version — MUST be TLS 1.3 or higher
- Documentation — external APIs MUST be well documented
SHOULD Disclose (Strong Recommendation)
- API Provider — organisation providing the API
- Resource Description — what information/functionality is exposed
- Exposure Level — Internal/External/Partner/Public
- API Type — REST/GraphQL/AsyncAPI/gRPC
- Current Version — clear version indication
- Access Control Guidance — how to gain access, granularity
- Authentication Method — API Keys/OAuth/etc.
- SLA Information — performance, availability metrics
- Rate Limits / Quotas — throttling information
- Deprecation/Retirement Notices — advance warning
- Roadmap — planned evolution
- Consumer Registration — onboarding process
SHOULD Provide via Developer Portal
- Discovery Mechanism
- Onboarding/Registration Process
- Education/Documentation
- Code Examples
- Sandbox/Test Environment
- Community/Forums
- Usage Metrics
- Published SLAs
References
All citations trace to the following authoritative documents:
| Document |
URI Prefix |
Full Reference |
| Part A: API Concepts and Management |
nz/dia-apis-parta/2022/en/ |
DocRef |
| Part B: API Security |
nz/dia-apis-partb/2022/en/ |
DocRef |
| Part C: API Development |
nz/dia-apis-partc/2022/en/ |
DocRef |
| NZ API Standard (Draft) |
nz/dia/nz-api-standard/draft/en/ |
DocRef |
Document Status: DRAFT
Generated: December 2025
All fields include traceable DocRef citations to authoritative NZ API Guidelines