type: string

description: The relationship to the request — for example, self that contains the resource that was requested or {object name}, a link to a resource that is related to the requested resource

href:

type: string

description: A link to the related resource. In an error scenario this is likely to be something such as a link to a support portal.

_links:

type: array

items:

properties:

rel:

type: string

description: The relationship to the request — for example, self that contains the resource that was requested or {object name}, a link to a resource that is related to the requested resource

href:

type: string

description: A link to the related resource

6. Appendix D — Synchronous / asynchronous example specifications

6.1. OpenAPI 3.0

To visualise, paste the content below into the OpenAPI editor SwaggerEditor.

Example

openapi: 3.0.0

info:

version: 1.0.0

title: Example Agency Claims API

description: A sample API specification demonstrating OpenAPI capabilities — this is for

example purposes only

termsOfService: https:// api.example.govt.nz/termsandconditions/

contact:

name: Example Agency API team

email: exampleteam@api.govt.nz

url: https://agency.govt.nz

paths:

"/claims":

get:

description: Retrieve details of a claim

tags:

\- get claim

security:

\- AuthorizationCode:

\- read:claims

responses:

200:

description: OK

content:

application/json:

schema:

$ref: "#/components/schemas/claims"

post:

description: Create a claim

tags:

\- Create CLaim

security:

\- AuthorizationCode:

\- write:claims

requestBody:

$ref: "#/components/schemas/createClaim"

responses:

"201":

description: Created

content:

application/json:

schema:

$ref: "#/components/schemas/claims"

default:

description: Error response

content:

application/json:

schema:

$ref: "#/components/schemas/errorModel"

components:

securitySchemes:

AuthorizationCode:

type: oauth2

flows:

authorizationCode:

authorizationUrl: https:// api.example.govt.nz/web

tokenUrl: https:// api.example.govt.nz/oauth2/token

scopes:

read:claims: Grants read access to a claim resource

write:claims: Grants write (update) access to an existing claims resource

schemas:

createClaim:

description: Create Claim Model

type: object

properties:

customerName:

type: string

example: "John Henry Ford"

claimDetail:

type: string

description: Claims details

example: This is a long string describing the claim for evaluation......

claims:

description: Claim Response Model

type: object

properties:

claimId:

type: string

format: uuid

description: Unique identifier for the claim

description:

type: string

description: A short description of the claim

status:

type: string

enum: ["PROCESSING","REJECTED","ACCEPTED"]

claimUri:

type: string

description: Resource identifier for the claim

example: "https://api.exampleagency.govt.nz/claims/{claimId}"

errorModel:

type: object

properties:

errors:

type: array

items:

description: An array of error items containing error codes and descriptions.

Note that the error descriptions will be normalised.

properties:

code:

type: integer

format: int32

description: An error code — should be used in conjunction with the HTPP

response code.

description:

type: string

description: A short description of the error.

_links:

type: array

items:

properties:

rel:

type: string

description: The relationship to the request — for example, self that contains the

resource that was requested or {object name}, a link to a

resource that is related to the requested resource

href:

type: string

description: A link to the related resource. In an error scenario this is

likely to be something such as a link to a support portal.

6.2. AsyncAPI 2.0

To visualise, paste the content below into the AsyncAPI playground AsyncAPI 2.0.0 playground.

Example

asyncapi: 2.0.0

info:

title: Claims Notifications

version: 1.0.0

description: This channel provides claim information and status notifications

servers:

production:

url: broker.exampleagency.govt.nz

protocol: amqps,secure-mqtt,https

description: This is "Example Agencies" broker.

security:

\- oauth2: []

channels:

claims/{claimId}:

publish:

message:

$ref: '#/components/messages/claim'

parameters:

claimId:

description: Unique identifier for the claim

schema:

type: string

format: uuid

subscribe:

message:

$ref: '#/components/messages/claim'

components:

messages:

claim:

payload:

type: object

properties:

claimId:

type: string

format: uuid

description: Unique identifier for the claim

description:

type: string

description: A short description of the claim

status:

type: string

enum: ["PROCESSING","REJECTED","ACCEPTED"]

claimUri:

type: string

description: Resource identifier for the claim

example: "https://api.exampleagency.govt.nz/claims/{claimId}"

securitySchemes:

user-password:

type: userPassword

oauth2:

type: oauth2

description: OAuth2 identity service for "Example Agency"

flows:

authorizationCode:

authorizationUrl: https://api.exampleagency.govt.nz/oauth/authorize

tokenUrl: https://api.exampleagency.govt.nz/oauth/token

scopes:

read:claims: Read details of claims

7. Appendix E — Standards for developing APIs

Learn more about the relevant standards for developing APIs.

In addition to the security standards captured in Part B: API security 2022, table 7 captures (current) API and web standards that should be considered as part of any API strategy.

For recommended standards and their current status, see the Government Digital Standards Catalogue.

Table 7: Standards for developing APIs

Standard or standard organisation

Description

OpenAPI

The OpenAPI specification defines a standard, language-agnostic interface to RESTful APIs that allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation or through network traffic inspection.

AsyncAPI

AsyncAPI is an open source initiative that seeks to improve the current state of Event-Driven Architectures (EDA). Their long-term goal is to make working with EDAs as easy as it is to work with REST APIs.

Hyper Text Transfer Protocol (HTTP)

Communication between client computers and web servers is done by sending HTTP requests and receiving HTTP responses. In practice, most RESTful APIs use HTTP as a transport layer and rely on the use of HTTP verbs, like POST, GET, PUT and DELETE.

OAuth2 / OIDC

The OAuth 2.0 Authorization Framework (OAuth2) is an industry standard framework that enables third parties limited access to protected resources and is a commonly used authorisation approach for APIs. OpenID Connect (OIDC) is an identity layer on top of OAuth2 that allows consuming applications to request information about authenticated sessions and end users.

JSON / JSON Schema

JavaScript Object Notation (JSON) is an open standard for a lightweight format for storing and transporting data. It is a ‘self-describing’ notation and is easy for both humans and computers to understand.

JWT / JWS / JWE / JWK / JWA

These are a set of open standards for securely transmitting information between systems using JSON. They include the data structure for a JSON Web Token (JWT), how to sign a JWT (JSON Web Signature (JWS)), how to encrypt a JWT (JSON Web Encryption (JWE), and some JSON cryptography practices (JSON Web Key (JWK) and JSON Web Algorithms (JWA)).

Fast Healthcare Interoperability Resources (FHIR)

FHIR is an industry standard for exchanging healthcare information electronically. It was developed by the HL-7 standards organisation.

Payments New Zealand (PNZ) API Centre Standards

PNZ is an industry standard for Open Banking. The security profile is quite interesting in regards to capturing customer consent for third parties to act on their behalf.

Simple Object Access Protocol (SOAP)