"errors": [

{

"code": 12345,

"description": "There has been an error - retrying the request will not succeed. Please contact support"

},

{

"code": 98765,

"description": "A more detailed description of the error if appropriate"

}

],

"_links": [

{

"href": "https://support.example.govt.nz",

"rel": "support"

}

]

}

2. API governance

API governance helps save time and money because it ensures that APIs are built proactively to achieve specific goals and bring value to the agency.

API governance also helps agencies make intelligent decisions regarding API programmes and establish best practices for building, deploying and consuming APIs.

API governance should include:

specification and resource definitions — governing contracts and resource definitions help improve the consistency and reusability of APIs

style and pattern guidelines — standardising API design ensures APIs remain consistent and improve usability

automation — establishing guardrails to make it easier to comply with policies than not (for example, API scaffolding that automatically generates security and audit componentry for APIs or build pipelines that enforce security policies, such as coding standards and security scans)

life cycle — governing the life cycle of an API, from publication to versioning and deprecation to retirement

tracking and analytics — keeping track of where APIs are deployed, who is using them and how they are being used (this information helps inform other aspects of API governance)

a robust code review process — ensuring that your development teams understand the concepts laid out in these guidelines, and establishing a practice where collaborative code reviews are performed (it is recommended that software is developed using a branch strategy with at least one peer review required prior to code merge and deployment).

When your API designers and developers are on the same page regarding APIs, the more efficient, valuable and successful your API programmes will be. Governance is especially beneficial for agencies that have a large API programme or microservices architectures.

For more information, see API Governance: How Important Is It for API Strategy? — NORDIC APIs.

3. Appendix A — HTTP verbs — Required

3.1. GET

GET is used:

for retrieval of information

if the interaction is more like a question, that is, it is a safe operation such as a query.

The HTTP GET method is used to read (or retrieve) a representation of a resource. It can be used to retrieve information about an individual resource (for example, ‘customers/123456’) or to retrieve a collection (list) of resources (for example, customers).

In the ‘happy’ (non-error) path, GET returns a representation in JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST) if the requested resource does not exist.

According to the HTTP specification, GET (along with HEAD) requests are used only to read data and not change it. Therefore, they are considered safe when used this way. That is, they can be called without risk of data modification or corruption — calling it once has the same effect as calling it 10 times. GET is idempotent, which means that making multiple identical requests ends up having the same result as a single request. Do not expose unsafe operations via GET — it should never modify any resources on the server.

3.1.1.Examples

Example

GET https://api.example.govt.nz/passengers/12345

Accept: application/json,version=1.*

Accept-Encoding: gzip,deflate

Host: api.example.com

Example

#Success Response

Content-Length: 612

Location: https://api.example.govt.nz/passengers/12345

Date: Fri Jul 08 16:52:21 NZST 2016

CorrelationID: 65347f577ade5f7750234abb

Transaction-Id: 65347f577bde5949ac7bd448

{

"id": 12345

"names": {

"firstName": "John",

"middleName": "Howard",

"lastName": "Doe",

"salutation": "Mr John Doe",

"title": "Mr"

},

"addresses": [

{

"type": "home",

"address1": "1 Some Street",

"address2": "Some Suburb",

"address3": "Some City",

"address4": null,

"country": "New Zealand",

"postcode": 1111

},

{

"type": "business",

"address1": "2 Work Street",

"address2": "Work Suburb",

"address3": "Work City",

"address4": null,

"country": "New Zealand",

"postcode": 2222

}

]

}

Example

GET https://api.example.govt.nz/passengers/12345/flights

GET https://api.example.govt.nz/schools/98765/learners

Some API GET calls will return a single resource item while some calls will return a collection of resource items. See [section 1.7.6. Singletons versus collections](/dmsdocument/> 232~api-guidelines-part-c-api-development-2022/html#singletons-collections) for more details.

3.2. POST

POST is used:

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 perceive (for example, a subscription to a service)

if the user is held accountable for the results of the interaction.

The POST verb is most often utilised to create new resources. In particular, it is used to create sub-resources, that is, subordinate to some other (for example, parent) resource. When creating a new resource by a POST to the parent, the API takes care of associating the new resource with the parent, assigning an ID (new resource URI) and so on. On successful creation, POST returns an HTTP status 201 (CREATED), with a Location header containing a link to the newly created resource.

POST is neither safe nor idempotent. It is therefore recommended for non-idempotent resource requests. Making 2 identical POST requests will most likely result in 2 resources containing the same information.

The body content of a POST request will differ to that of a PUT, as the provider will create certain values such as a unique identifier for the resource and its creation date.

In many cases a POST may have a small subset of the data that can exist on a resource — a subsequent PUT to the resource can be performed to populate the data.

3.2.1. Examples

Example

#Create a new passenger resource

POST https://api.example.govt.nz/passengers

{

"names": {

"firstName": "John",

"middleName": "Howard",

"lastName": "Doe",

"salutation": "Mr John Doe",

"title": "Mr"

},

"addresses": [

{

"type": "home",

"address1": "1 Some Street",

"address2": "Some Suburb",

"address3": "Some City",

"address4": null,

"country": "New Zealand",

"postcode": 1111

},

{

"type": "business",

"address1": "2 Work Street",

"address2": "Work Suburb",

"address3": "Work City",

"address4": null,

"country": "New Zealand",

"postcode": 2222

}

]

}

Example

#Successful resource creation response

HTTP/1.1 201 Created

Location: https://api.example.govt.nz/passengers/12345

Content-Location: https://api.example.govt.nz/passengers/12345

Content-Type: application/json

{

"id": 12345,

"names": {

"firstName": "John",

"middleName": "Howard",

"lastName": "Doe",

"salutation": "Mr John Doe",

"title": "Mr"

},

"addresses": [

{

"type": "home",

"address1": "1 Some Street",

"address2": "Some Suburb",

"address3": "Some City",

"address4": null,

"country": "New Zealand",

"postcode": 1111

},

{

"type": "business",

"address1": "2 Work Street",

"address2": "Work Suburb",

"address3": "Work City",

"address4": null,

"country": "New Zealand",

"postcode": 2222

}

]

}

3.3. PUT

PUT is used to :

update an existing resource item

replace an existing resource item.

PUT is most often utilised to update information, PUT-ing to a known resource URI with the request body containing the newly updated representation of the original resource.