Australia’s API design standard

What are APIs?

API stands for ‘application programing interface’ and within the web development context it usually refers to a set of specifications for how web commands will ‘communicate’ with each other. APIs are a structured way to represent data that an application has stored in its database. For example, a website page might request information from a customer resource (e.g. a road rule or a dataset) and return the results. Another example, this time from the API catalogue, is using the ABN Lookup API to include ABN information and search in a website or other application.

The API design standard

The National API Design Standards are part of API.gov.au, which is a joint initiative between the Digital Transformation Agency and the Australian Taxation Office. API standards help connect websites, databases and other software — which is essential for service unification. They also streamline API development, because developers can reference best practice API design and implement APIs in line with the standards. Importantly, the National API Design Standards also represent a whole-of-government approach, which delivers many benefits such as consolidation across government and reduced costs.

The standards focus on HTTP REST (Representational State Transfer). REST was chosen as the most widely used design standard around the world for data transfer to and from the internet.

The National API Design Standards are broken into 17 sections:

• Overview — a quick introduction to the standards, the goals, and contact details for state API teams

• Getting Started — overview information on when and how to apply the standards, including templates

• Definitions — definitions of key terminology

• WoG API Requirements — requirements across documentation, stability and design maturity

• Naming Conventions — conventions covering message formats, URI components, field names, link relation names, request headers and managing dates

• API Versioning — major and minor versioning, minor and patch documentation and end-of-life policy

• API Request — request headers, HTTP request methods, request payload formats and idempotency

• Query Parameters — pagination, filtering and sorting

• API Response — response headers, HTTP response codes and response payload

• Error Handling — error response payload, input validation and error samples

• API Security — including API design, transport security, authentication and authorisation, error handling, audit logs and gateway security features

• Hypermedia — including hypermedia linked data, hypermedia compliant API, and link relation type

• Pagination — query parameters, pagination response and out of range

• Networking — caching

• Webhooks — current guidance

• Testing — testing tools

• References — general references and API standards referenced

There’s also a template that developers can use to get started and the standards are also on GitHub.

Implementation rules for the API standards

The National API Design Standards can be applied across three categories:

• System-level APIs — it’s recommended that these APIs follow the standards

• Process-level APIs — these APIs should follow the standards

• Experience-level APIs — these APIs must follow the standards

Creating the API design standards

In the 6 December 2019 meeting of the Australian Data and Digital Council, ministers agreed to move forward with national standards to enable a common method of API development and interoperability between different IT systems.

According to an IT News article on the standards, they built on Victoria’s work on API standards. Victoria launched its whole-of-government API portal in April last year (see our blog on Victorian Government APIs).

Salsa Digital’s take

APIs are a key tool for digital transformation in government. They have the power to help consolidate government services, and standardisation will make this consolidation easier and provide a shared framework to build on. APIs also form part of Australia’s commitment around sharing, using and reusing government data, and are important to the open data and open government movements.