The URI references for resources should consistently use the same path structure to refer to resources. Sub-namespace or sub-folders should be avoided, to maintain path consistency. This allows application developers to have a predictable experience in case they are building URIs in code.

Template

/{version}/{namespace}/{resource}/{resource-id}/{sub-resource}/{sub-resource-id}

/{version}/{resource}/{resource-id}/{sub-resource}/{sub-resource-id}

Example

https://api.example.govt.nz/v2/biosecurity/trusted-travellers/33245/arrivals/P100782

https://api.example.govt.nz/v2/learners/43265/achievements/7281

1.5.5. Word separation

Hyphens have traditionally been used as word separators in URLs, as search engines (particularly Google) prefer a hyphen to split words because a hyphen is not a word character (as defined in regular expression language). This has led to hyphens, or kebab case, being the de facto standard in the interests of readability and Search Engine Optimisation (SEO).

Therefore, in order to keep URLs consistently formatted, path and query string parameters should be lower case with hyphen separators for multiword names.

Example

https://api.example.govt.nz/v1/example-service/search?sort-order=asc

1.5.6. Query arguments

Query arguments should be used to filter a response, for example, modify a returning result set. The general rule is if it changes the behaviour of the:

result set, then it should be a query argument

API, then it should be in the path.

Query arguments are generally used for:

sorting or ordering the result set — for example, sort-order=ascending

pagination — pagination is a query argument because it effectively acts as a filter and limits the result set returned. This is particularly useful with large response data sets. When using pagination, it is a good idea to inform the consumer where they can find previous and subsequent result sets using hypermedia (see section 1.7.7. HATEOAS).

Example

"_links": [

{

"rel": "next",

"href": "https://api.example.govt.nz/v1/example-service/search?limit=5&start=5"

},

{

"rel": "prev",

""href": "\https://api.example.govt.nz/v1/example-service/search?limit=5&start=0"

},

{

"rel": "self",

"href": "http://api.example.govt.nz/v1/example-service/search"

}

"href": "http://api.example.govt.nz/v1/example-service/search"

]

limiting the result set, for example, by specifying which fields to return. This approach can be complicated and is often a decision based on functionality versus complexity. For example, it may be desirable to be able to filter a result set to a specific set of objects. While this is possible, it is not a recommended approach. If this kind of flexibility is required in an API it could be a good time to consider the use of Open Data Protocol (OData).

in cases where response filtering is used, providers should ensure that they use a JSON schema by default so that consumers have the ability to understand the entire resource and do not need to query the resource for the message structure.

Example

# Get a filtered result set for a learner

GET

https://api.example.govt.nz/v2/learners/33245?fields=firstName,lastName,dateOfBirth

{

"firstName": "Mary",

"lastName": "Contrary",

"dateOfBirth": "12-01-1974",

"_links": [

{

"rel": "self",

"href": "https://api.example.govt.nz/v2/learners/33245?fields=firstName,lastName,dateOfBirth"

}

]

}

1.6. HTTP headers

1.6.1. Request headers

Table 4: Request headers

Header

Usage

GET

POST

PUT

DELETE

Accept

Indicates desired format of the response. If set to a value that cannot be supported by the server, API responds with 406 (Not Acceptable)

Required

Required

Required

N/A

Content-Type

Indicates the format of the payload provided on the request. If not supported by the server, API responds with 415 (Unsupported Media Type)

N/A

Required

Required

N/A

Authorisation

To provide authorisation information — type and token, depending on authorisation type. If token is not valid for the request, API responds with 401 (Unauthorized)

Required, unless a public API

Required, unless a public API

Required, unless a public API

Required, unless a public API

Accept-Encoding

Advertises what compression algorithm the consuming application is able to understand. If encoding not supported by the server, API responds with uncompressed response

Should use

Should use, if response body expected

Should use, if response body expected

N/A

{API Key Header}

Note: there is no set naming standard for an API Key Header

Send the API keys with every request. If keys are not valid, API response with 401 (Not authorised)

Required, if issued

Required, if issued

Required, if issued

Required, if issued

If_Modified_Since/If-None-Match

Makes the request conditional —the server will respond with the resource only if the specified condition is met. If condition is not met, API responds with 304 (Not Modified)

Shoud use

N/A

N/A

N/A

{Request tracking Headers}

Note: there is no set naming standard for a transaction ID header

Unique identifier that can be used to trace a request throughout its life cycle

Shoud use

Shoud use

Shoud use

Shoud use

1.6.2. Response headers

Table 5: Response headers

Response Header

Usage

GET

POST

PUT

DELETE

Content-Type

Indicates the format type of the response

Required

Required, if response body returned

Required, if response body returned

N/A

Location

Indicates the absolute URI of the newly created resource item

Required for 302 redirect

Should use, if resource created

N/A

N/A

Content-Location

Indicates the absolute URI of the requested resource

Should use

Should use, if resource returned

Should use

N/A

Cache-Control

Directives to control caching behaviour external to the API layer (for example, Content Delivery Network (CDN) caching)

Should use

Should use

Should use

N/A

Expires

Used in conjunction with Cache-Control for backwards compatibility

Should use

Should use

Should use

Should use

ETag

Concurrency control header

Should use

Should use

Should use

N/A

1.6.3. Customer X-HTTP headers

X-notation headers have been deprecated as per Request for Comments (RFC) 6648 and should not be used. This standard appreciates that X-notation headers are widely used however this guideline recommends that where an agency is defining a custom header the X-notation should not be used and the agency defines a custom header notation that is relevant. For example, X-Request-Id should be redefined as Request-Id.

RFC 6648 — Internet Engineering Task Force (IETF)

1.7. Returned content

The returned content is the body of the message that the API returns in response to a request. This usually relates to the resource that was requested.

1.7.1. Resource scope

The amount of data to return about a resource depends on several factors:

Business context — does all the resource information being returned have relevance to the business process or activity consumers will use it for?

Payload size and network efficiency — how much information does the resource contain, and is it so bulky it could impact network performance?

Usefulness — is the information in the returned content always useful to the consumer, or is it something they may need once but never again?

Analysis of the full resource data against these factors should help determine how much resource data is returned in the response.

1.7.2. Formats