The Content-type header is required for all requests that include a request body like POST, PUT, DELETE.

Example

#PUT https://api.example.govt.nz/v2/learners/33245

Accept: application/json,version=1.*

Content-Type: application/json

Authorization: Bearer x6TLB4JaomezC5rJ3CIl3KxxNinq

{

"id": "33245",

"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

}

],

"qualifications":[

{

"id": "1a4rf54ee345",

"type": "Some type",

"provider": "University of life",

"providerId": "0o9i8u7y6tt"

},

{

"id": "8u7y6t5r4ee",

"type": "Another type",

"provider": "School xyz",

"providerId": "1q2w3e4r5tt"

}

]

}

4.1.3. Authorization

Most API requests will be authorised. The Authorization header should be used for this purpose and no other. Note that the Authorization header is not the best place for an API key.

The Authorization header is comprised of a type and a token depending on the authorization type.

Example

#OAuth Access Token

Authorization: Bearer x6TLB4JaomezC5rJ3CIl3KxxNinq

#HTTP Basic

Authorization: Basic c29tZXVzZXI6c29tZSBwYXNzd29yZA==

4.1.4. Accept-Encoding — Recommended

In some cases, especially where API responses are very large, it may be worth compressing HTTP responses.

Note: Where possible it is best to avoid large payloads in API responses, however, this may not always be possible.

An Accept-Encoding value of gzip instructs a provider that supports HTTP compression that the consuming application supports compressed responses.

Example

Accept-Encoding: gzip,deflate

4.1.5. API key — Required

An API key header issued to a consuming application should be sent with every request made to the API. The name of the header is up to the agency, but it should not be an X- prefixed header as this use is deprecated. Sometimes API keys are passed in URIs, however, this is not considered best practice and should be avoided.

Example

KeyID: pX680LyiKasUBWLuZJ8AVBHVQK03Ghtr

4.1.6. If-Modified-Since / If-None-Match — Recommended

The If-Modified-Since header is a pre-condition header used to instruct a client on the validity of the resource requested. Note that pre-condition handling is not required, but should be considered where appropriate. Pre-condition control can be a complex topic so in some cases the complexity may eclipse the value.

Conditional header standards are available in Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests RFC 7232 — IETF.

A consuming application can specify an If-Modified-Since header with a date and time. The server checks the resource to see the last modified time. If the last modification was before the date / time specified in the header, the server will respond with an HTTP 304 (NOT MODIFIED) status code telling the consuming application that the resource they requested has not changed and therefore there is no need to return the full payload in the response.

When using If-Modified-Since headers you should also implement ETag as discussed in section 1.6. HTTP headers.

Example

\# Request with If-Modified-Since and If-None-Match headers

If-Modified-Since: Wed, 18 Jun 2016 22:00:00 GMT

If-None-Match: "686897696a7c876b7e"

The If-None-Match header indicates to the provider the ETag for the resource that it currently holds for that resource.

Example response

\# Response that indicates the client’s current representation is still

\# valid

HTTP/1.1 304 Not Modified

ETag: "686897696a7c876b7e"

Content-Length: 0

4.1.7. Request tracking headers — Recommended

To support the tracking of API requests it is a good idea to apply a transaction ID header that will enable analysts to trace a request throughout its life cycle.

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

There are 2 common approaches to this:

To request that the consuming application generate a unique transaction ID and the provider will capture it and respond with a corresponding correlation ID.

To allow the provider to generate the transaction ID as close to the edge of its domain as possible, and respond to the consuming application with that transaction ID. In this case a consuming application administrator or developer should capture and log that transaction ID for audit purposes so that it can be relayed to agency analysts if required.

Example request

#Request that includes a consuming application generated transaction

#ID

Request-Transaction-Id: c188cb0e-1a09-4184-890c-0f0bb2255425

Example response

#Response to a consuming application that provided a client generated #transaction ID

Request-Transaction-Id: c188cb0e-1a09-4184-890c-0f0bb2255425

Response-Correlation-Id: 514dbf50-4475-4e4d-86ee-e2001f158026

#Response to a consuming application where there was no client #generated transaction ID

#Note that the server has generated the transaction ID

Response-Correlation-Id: c188cb0e-1a09-4184-890c-0f0bb2255425

4.2. Response headers

Response headers are supplied by the provider and must contain Content-Type.

4.2.1. Content-Type — Required

The Content-Type must be returned in the response, and indicate the format type the response content is in, for example, ‘Content-Type: application/json’. The Content-Type header should also include the version of the API that processed the request, for example, ‘Content-Type: application/json,version=1.1’.

4.2.2. Location — Recommended

Where a new resource item has been created (POST), the server should respond with a 201 (Created) HTTP header and a Location header indicating the URI of the newly created resource item, for example, ‘Location: https://api.example.govt.nz/v1/crown-property/198373’.

A Location header should also be returned by a server when it sends a 3** HTTP response, indicating a temporary or permanent redirection.

A Location header can be, as recommended by this standard, absolute, for example, ‘Location: https://api.example.govt.nz/v1/crown-property/198373’ or relative, for example, ‘Location: /v1/crown-property/198373’.

4.2.3. Content-Location — Recommended

The Content-Location header indicates the location of the requested resource. It should be an absolute and not a relative link.

Example

#GET https://api.example.govt.nz/v1/crown-property/198373

Content-Type: application/json

Content-Location: https://api.example.govt.nz/v1/crown-property/198373

{

"propertyid": 12345,

"address1": "1 Some Street",

"address2": "Some Suburb",

"address3": "Some City",

"address4": null,

"country": "New Zealand",

"postcode": 1111,

"type": "commercial"

}

4.2.4. Cache-Control — Recommended

It is important to consider caching when designing APIs, to ensure that the APIs you build can perform at scale. The Cache-Control header is only concerned with caching that occurs externally to the API layer. Common examples may be client-side caching or caching within a Content Delivery Network (CDN). This header should not be concerned with caching mechanisms within the API layer such as response caches or object caches, which require a different caching strategy.

The Cache-Control header is comprised of the following:

private|public — indicates if the cache is specific to the consumer or not. A setting of private will prevent the cache from being persisted in a public cache.

no-cache — instructs a cache to revalidate the resource every time.

no-store — instructs a cache not to store the response. It also ensures that no part of the request is stored too.

max-age — instructs the cache on expiry time. This can be used but it makes more sense to use the Expires header discussed in section 4.2.5. Expires.