There are several API modelling languages available for defining the interface specification. Some are proprietary (for example, REST API Modelling Language (RAML), API Blueprint) while others are machine readable but not human readable (for example, Web API Description Language (WADL)).

The most commonly used API modelling language today is an open standard known as the OpenAPI Specification (formerly Swagger) maintained by the Open API Initiative. This initiative is supported by many of the main commercial entities in IT (Google, IBM, Microsoft, Atlassian, Paypal). It offers a standard, programming language-agnostic (JSON / YAML Ain’t Markup Language (YAML)) interface to REST APIs that allows both humans and computers to discover and understand the capabilities of the service.

It is important to use a modelling language to define the API interface specification as essentially it is text or code and can be maintained using source code management systems.

It is recommended to use OpenAPI / Swagger as the interface specification language for all APIs being developed.

OpenAPI/Swagger — OpenAPIs

1.2.9. Orchestration

As a general rule using APIs as an orchestration tool is not recommended. This is due to the complexity that this can introduce to an API architecture. That said, however, simple orchestration may in some cases be appropriate. An example of this may be a mashup API that creates a new logical API resource by combining related data held in 2 or more backend systems.

A mashup is not appropriate when you create an API that merges 2 distinct API products together. If a consumer requires this functionality the mashup should be performed by the consuming application.

Other examples of simple orchestration could include mediation such as message transformation (JSON to eXtensible Markup Language (XML) or canonical message model transformation).

1.2.10. Software development kits (SDK)

It is recommended that API providers offer an SDK to developers of consuming applications.

An SDK can be considered the implementation toolset for use of an agency’s APIs. By providing developers with an SDK they can build applications faster without having to understand all of the API’s complexities. An SDK should provide sample code that explains the functionality of your API to potential application developers.

An example of a public service API SDK can be found at the US Department of Labor GitHub repository Publication / Catalogue — Github.

Once an API is in sufficient state to be offered to API consumers, the API definition should be published to an API catalogue. The primary API discoverer is the developer, so an external API must be well documented, and provide accurate and up-to-date guidance via the catalogue.

Government are considering options for a central point of discovery for externally accessible public sector APIs.

Publishing to a catalogue is recommended for internal APIs.

Publishing to a catalogue is required for external APIs.

1.3. Architectural and deployment patterns

Table 2 identifies some architectural and deployment patterns that bear further investigation. There are a number of vendor specific references that are also available however these guidelines do not recommend any particular one.

Table 2: Architectural and deployment process

Pattern

Reference

Microservices

Microservices Guide — MartinFowler.com

API management

Understanding API management, API gateway, and API manager — Nordic APIs

Observability

* Domain-Oriented Observability — MartinFowler.com

* Chapter 4. The Three Pillars of Observability — O’Reilly

API publication / discovery

Gathering My Thoughts on API Discovery — API Evangelist

Hybrid deployments

Making Sense of a Multi-Cloud API Approach — Nordic APIs

Service mesh

* Introduction to Service Mesh — Nordic APIs

* Chapter 1. Service Mesh Fundamentals — O’Reilly

1.4. HTTP verbs

Access to REST APIs must be via the standard HTTP verbs: GET, PUT, POST, DELETE in line with the W3C Standard.

Table 3: HTTP verbs

Verb

Common usage

GET

* For retrieval of information

* If the interaction is more like a question, for example, it is a safe operation such as a query

POST

* To create a piece of information or resource item

* To spawn an action

* If the interaction is like placing an order

* If the interaction changes the state of the resource in a way that the user would receive (for example, a subscription to a service)

* If the user will be held accountable for the results of the interaction

PUT

* To update an existing resource item

* To replace an existing resource item

DELETE

To delete an existing resource item

OPTIONS

To retrieve information about what the consumer is allowed to do with the resource

PATCH

Not recommended due to complexity

HEAD

Rarely used, but used to retrieve metadata about a resource

1.5. URI construction

Uniform Resource Identifier (URI) construction is important in that it is the door through which consumers enter to obtain agency resources. It should be intuitive and easy to guess what an endpoint does just by looking at the URI and HTTP verb, without needing to see a query string. As basic guidance, endpoint URLs should advertise resources, and avoid verbs.

In some situations an implemented standard may define the URI structure for you. A good example of this is Resource — FHIR v4.0.1 — Fast Healthcare Interoperability Resources (FHIR).

1.5.1. API offering — Recommended

Is it recommended that agencies make it clear in the URL that their offering is an API:

Example

https://api.example.govt.nz

1.5.2. Version

APIs should have a clear indication of the version, so that application developers can ensure they are using the appropriate version for their consuming application.

Header-based versioning is recommended (see section 1.10. API version control) however, it is recognised that some API infrastructure does not readily support header-based versioning.

URL-based versioning is a viable alternative, as the version number in the URL should only change when major revisions have been made and the interface has changed substantially without backwards compatibility. For URL-based versioning the URI should include /vN with the major version (N) and v as a prefix. Agencies should not include minor version numbers when using version numbers in the API paths.

Template

/v{version}/

Example

#Get details for provider id 123435 – version 1 of the API

GET https://api.example.govt.nz/v1/providers/12345

Accept: application/json

Host: api.example.govt.nz

#Get details for provider id 123435 – version 2 of the API

GET https://api.example.govt.nz/v2/providers/12345

Accept: application/json

Host: api.example.govt.nz

1.5.3. Namespaces

For APIs where an agency holds multiple responsibilities that may result in overlapping resource naming (for example, MBIE could have the resource ‘accommodation’ in 2 contexts: tenancy/contracts, tourism/contracts) it is recommended that namespaces be used to avoid any ambiguity. The namespace would be the first noun in the URI and should reflect the function of government being offered by this API. Namespaces may be singular or plural, depending on the situation.

Template

/{version}/{namespace}/

Example

/v1/biosecurity/

1.5.4. Resources and sub-resources — Recommended

Resource names should be noun-based and collection resource names should be plural nouns, for example, ‘/passengers’ in lower case. Resource naming should be short, simple and clearly understandable. It should also be human-guessable, avoiding technical or specialist terms where possible.

Sub-resources must appear under the resource they relate to, but should go no more than 3 deep, for example, ‘/resource/id/sub-resource/id/sub-sub-resource’. If you reach a third level of granularity (sub-sub-resource), it may be worth reviewing your resource construction to see if it is actually a combination of multiple first or second level resources.