API Catalogue

Building a Cross-Government API Catalogue

A plain language summary of the design, outputs, and approach

View the published catalogue: NZ Government API Catalogue on DocRef

What we set out to do

New Zealand government agencies offer hundreds of APIs - ways for software systems to connect and share data. But there's no single place to find them all. Developers working on government projects often don't know what APIs exist, who provides them, or how to access them.

We designed a catalogue to solve this. The goal was simple: create a single, searchable list of government APIs that agencies can easily contribute to and that grows more useful over time.

How we approached the design

Starting with requirements, not assumptions

Rather than inventing fields from scratch, we grounded every piece of information in the catalogue on the NZ API Guidelines - the official standards for government APIs. This means every field we ask agencies to report has a clear purpose backed by existing policy.

We identified 33 possible fields across categories like identity, classification, access, versioning, authentication, and service levels. Each one traces back to a specific requirement or recommendation in the guidelines.

Designing for growth

We recognised that asking agencies to report 33 fields upfront would be a barrier. So we organised the fields into five phases:

Phase What it covers Fields
Phase 1 (MVP) Basic discovery - what exists and where to find it 8
Phase 2 Enhanced discovery - authentication, versioning, rate limits 15
Phase 3 Lifecycle - roadmaps, changelogs, deprecation dates 19
Phase 4 Full specification - embedded specs, SLAs, sandbox environments 26
Phase 5 Complete - support resources, community links, status pages 33

This lets agencies start simple and add detail over time. An API with just a name, description, and documentation link is still useful in the catalogue.

Choosing a format that works for humans and machines

We needed a format that:

  • People can read and edit without special tools
  • Machines can process and query
  • Supports stable, linkable references to every piece of information
  • Versions cleanly over time

We chose structured markdown with embedded JSON. The document reads naturally as a web page, but every section contains machine-readable data that can be extracted and queried.

What we produced

1. Data Structure Specification

A complete technical specification defining:

  • The three-level hierarchy: Agency → API → Attribute
  • JSON schemas for each attribute type (identity, classification, access, etc.)
  • How identifiers are generated for every element
  • How the document maps to the DocRef format for publishing

2. First Catalogue Draft

A working catalogue containing 48 APIs from 15 government agencies, structured according to the specification. This includes major API providers like MBIE (21 APIs), NZTA, DIA, Stats NZ, and others.

Current data coverage:

Field Status
Agency and API names ✅ Complete
Descriptions ✅ Mostly complete
Documentation URLs ✅ Complete
Exposure level, API type ⏳ To be collected
Contact emails, spec URLs ⏳ To be collected

3. Entry Submission Form

A simple HTML form that agencies can use to report their APIs. The form:

  • Guides users through each required field
  • Uses dropdowns for constrained values (so you can't enter invalid data)
  • Generates a properly formatted markdown file
  • Downloads the file ready for submission

No login, no database, no technical knowledge required. Fill in the form, download the file, email it to GCDO.

How the system works

The catalogue as a document

The catalogue is a single markdown file. It looks like this:

# New Zealand Government API Catalogue

## Ministry of Business, Innovation and Employment

### Companies Register API

#### identity
{name, description, contact email}

#### classification  
{exposure level, API type}

#### access
{documentation URL, specification URL}

### NZBN API
...

## Department of Internal Affairs

### Charities Register API
...

Each heading level has a purpose:

  • H2 = Agency
  • H3 = API (or agency information)
  • H4 = Attribute group (identity, classification, access)
  • Code block = Structured data in JSON

Every element gets a stable address

When published through DocRef, every element in the catalogue gets a unique, permanent URL:

  • The whole catalogue: /nz/dia/api-catalogue/1/en/
  • MBIE as an agency: /nz/dia/api-catalogue/1/en/#agency9
  • The Companies API: /nz/dia/api-catalogue/1/en/#agency9-api2
  • Its classification data: /nz/dia/api-catalogue/1/en/#agency9-api2-attribute2-pf1

These URLs are stable across time. When the catalogue is updated, a new version is published (v2, v3, etc.) but old versions remain accessible. Citations never break.

The catalogue becomes a dataset

The structured format means the catalogue can be exported as a spreadsheet or database. You could:

  • Filter to show only public REST APIs
  • List all APIs from a specific agency
  • Find APIs missing documentation
  • Track which APIs have SLAs defined

The document and the dataset are the same information in different forms.

How agencies contribute

For a new API

  1. Go to the entry form (HTML file, works in any browser)
  2. Fill in the fields - agency name, API name, description, exposure level, type, documentation URL
  3. Click "Download Markdown File"
  4. Email the file to GCDO@dia.govt.nz

That's it. No accounts, no systems to learn.

For an existing agency adding another API

Same process, but check the "agency already exists" box. The form will only generate the API entry, not duplicate the agency header.

For updates to existing entries

Agencies can submit corrections or additions the same way. GCDO reviews and merges changes into the next catalogue version.

How the catalogue grows over time

Adding more APIs

As agencies submit entries, the catalogue expands. The goal is to capture all publicly-relevant government APIs - likely 200-400 in total.

Adding more detail

Agencies can progressively enhance their entries:

  • Start with Phase 1: Name, description, docs URL
  • Add Phase 2 later: Version number, auth method, rate limits
  • Add Phase 3 when ready: Roadmap links, deprecation notices
  • Full detail eventually: SLAs, sandbox URLs, support resources

There's no requirement to complete everything at once.

Version control

Each published version of the catalogue is preserved:

  • Version 1 (December 2025): 48 APIs, Phase 1 fields
  • Version 2 (future): More APIs, some Phase 2 fields populated
  • Version 3 (future): Even more coverage

Researchers, auditors, or anyone who cited a specific version can always access exactly what they referenced.

Why this approach works

Low barrier to entry

Agencies don't need to adopt new systems or learn new tools. A markdown file and an email is all it takes to contribute.

Flexible but structured

The catalogue accommodates partial information while maintaining a consistent structure. An API with minimal data sits alongside one with complete detail - both are valid, both are useful.

Standards-aligned

Every field traces to the NZ API Guidelines. The catalogue doesn't invent new requirements - it helps agencies meet existing ones.

Future-proof

The phased approach means the catalogue can evolve as needs change. New fields can be added in future phases without breaking what already exists.

Machine-readable

Despite being a simple document, the catalogue supports sophisticated queries and integrations. It can feed into API marketplaces, developer portals, or compliance dashboards.

Supporting Materials

The following files document the design process, technical specifications, and tools used to create the catalogue:

File Purpose Description
Data Structure Specification Technical reference Authoritative specification defining phases, schemas, identifiers, and DocRef mapping
Disclosure Requirements (Traceable) Compliance basis All disclosure fields with traceable citations to the NZ API Guidelines
Entry Form Submission tool HTML form for agencies to submit new API entries
Sample Entry Template Example showing correct format for a catalogue entry
Catalogue Draft Raw output The markdown source file published to DocRef

Current status

Component Status
Data structure specification ✅ Complete
Phase 1 catalogue (48 APIs) ✅ Complete
Entry submission form ✅ Complete
Data enrichment (missing fields) 🔄 In progress
DocRef publication ⏳ Pending
Agency outreach for contributions ⏳ Pending

Next steps

  1. Populate missing fields - Work with agencies to add exposure levels and API types for existing entries

  2. Publish via DocRef - Generate stable URLs and the queryable dataset

  3. Invite contributions - Distribute the entry form to agencies not yet in the catalogue

  4. Iterate - Release updated versions as new APIs are added and existing entries are enhanced

Summary

We've built a simple, extensible system for cataloguing government APIs. It's grounded in existing standards, designed for growth, and requires minimal effort from agencies to contribute. The format supports both human readers and machine processing, with stable URLs for every piece of information.

The first version contains 48 APIs from 15 agencies. With continued contributions, it will grow into a comprehensive directory of New Zealand government APIs - making it easier for developers to discover, evaluate, and integrate government services.

December 2025