SOAP is deprecated for the NZ government — the Government Enterprise Architecture Group (GEAG) has determined that the standard should not be used for new work, but may still be in use for existing APIs.

Financial Grade API (FAPI) Security Profile

FAPI is another industry standard for the financial sector. It is an example of good security profile practices.

Pan European Public Procurement Online (Peppol)

Peppol is a global standardised framework that enables businesses to exchange procurement documents electronically. To do this, Peppol provides and maintains artefacts and specifications to make it possible for businesses using different systems to ‘speak’ to each other. The use of Peppol is governed by a multi-lateral agreement structure, owned and maintained by OpenPeppol.

Internet Engineering Task Force (IETF)

IETF is a large open international community concerned with the evolution of the Internet architecture and the smooth operation of the Internet. Their mission is to make the Internet work better by producing high quality, relevant technical documents that influence the way people design, use and manage the Internet. Many of the standards listed were developed through the IETF.

Standards New Zealand

A business unit within the Ministry of Business, Innovation and Employment which specialises in managing the development of standards. They also publish and sell NZ, joint Australia–NZ, and international standards.

Stats NZ: Standards and classifications

Information about the standards and classifications Stats NZ use and maintain, news about reviews, and tools to help classify and code responses.

Health Information Standards Organisation (HISO)

HISO supports and promotes the development and adoption of fit-for-purpose health information standards for the NZ health system.

Data Content Requirements

A documented set of government data content requirements listed on Data.govt.nz — Register of government mandated data standards.

8. Glossary of terms

Analytics Analytics in the context of these guidelines is the capturing and reporting of API usage.

API (Application Programming Interface) An API is a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another.

API catalogue The API delivery component that lists the APIs offered, along with their interface specification and guidance on how to gain access and use the APIs.

API developer The organisation (or person) who creates the API and maintains the interface specification for the API. An API developer creates and documents an agency’s APIs. API developers generally have a good understanding of an agency’s function.

API developer portal The API delivery component that allows API providers to engage with, onboard, educate and manage application developers whether inside or outside the organisation. These management activities will generally include registration, documentation, analytics and so on.

API gateway The API delivery component that allows API providers to offer APIs to the outside world. This component (physical or virtual) hosts the APIs ready for consumers to access. It provides an API provider with the ability to control who has access to their APIs by enforcing policies for access control. Some API gateways also offer additional capabilities.

API manager The API delivery component that allows API providers to control an API’s visibility and behaviour. It is usually exposed as a UI / console to internal staff only, as it is seen as an administration component. It offers a variety of capabilities, including API registration and catalogue administration.

API provider The organisation that provides the API to expose a resource (information or functionality) for consumers.

Application The software behind the API that provides the business logic for the resource.

Application developer Software developer or organisation that builds consuming applications that use the API. An application developer needs to be able to discover, understand and access your APIs. They can be internal to your agency, developers that work with trusted partners, developers from other agencies or developers from the private sector.

Atomicity One of the ACID (Atomicity, Consistency, Isolation, Durability) transaction properties. An atomic transaction is an indivisible and irreducible series of database operations such that either all occurs, or nothing occurs. A guarantee of atomicity prevents updates to the database occurring only partially, which can cause greater problems than rejecting the whole series outright. As a consequence, the transaction cannot be observed to be in progress by another database client. At one moment in time, it has not yet happened, and at the next it has already occurred in whole (or nothing happened if the transaction was cancelled in progress).

Consumers Customers, consuming applications and application developers who use the API.

Consuming application Any application (on any device) that consumes or uses an API.

Context Context in these guidelines generally refers to request context. For example, a JWT (JSON Web Token) may contain information about the customer initiating an API request.

Customers People (or organisations) that use the consuming applications to access the API resources the API provider is offering.

DELETE One of the most common HTTP methods, DELETE is used to delete a resource specified by its URI.

Discovery The ability for application developers to find resources and associated APIs to use in their consuming applications.

GET An HTTP request method, GET is applied while requesting information from a particular source. It is also used to get a specific variable derived from a group.

HEAD An HTTP request method, HEAD asks for a response identical to a GET request, but without the response body. It is used to send the request and retrieve just the HTTP header as response. For example, a client application can issue a HEAD request to check the size of a file (from HTTP headers) without downloading it.

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.

Idempotent An HTTP method where making multiple identical requests ends up having the same result as a single request.

PATCH An HTTP request method, PATCH is a request for making partial changes to an existing resource. The PATCH method provides an entity containing a list of changes to be applied to the resource requested using the URI.

POST One of the most common HTTP methods for retrieving from and sending data to a server, the POST method sends data to the server and creates a new resource. The resource it creates is subordinate to some other parent resource. When a new resource is POSTed to the parent, the API service will automatically associate the new resource by assigning it a new resource URI. In short, this method is used to create a new data entry.

Publish The act of releasing the interface specification and associated API to a location accessible by application developers.

PUT One of the most common HTTP methods for retrieving from and sending data to a server, the PUT method is most often used to update an existing resource. If you want to update a specific resource (which comes with a specific URI), you can call the PUT method to that resource URI with the request body containing the complete new version of the resource you are trying to update.

Resource The information or functionality exposed by the API.

State State defines the point in time record of an in-flight transaction. Some systems maintain ‘user state’ for a period of time to enable a transaction to be continued from the point of last recorded state. APIs are usually, but not always, considered stateless.

9. Glossary of acronyms

API Application Programming Interface