Implementation requirements

In order to reduce the potential for confusion, the following guidance is given to assist Standards Users in their understanding of the standards implementation requirements.

It is not possible, or advisable, to set all endpoints, fields and other elements to mandatory. Some API providers may not have all data items available, or may not be able to support all functionality. Realising this, the API Standards mark endpoints and fields as mandatory whenever possible, in order to provide consistency, but also allow for a degree of flexibility.

The following elements can be marked as mandatory or optional in the standards:

API Endpoints that identify actions on Resources
API request data fields
API response data fields
API query parameters
API path parameters
HTTP request and response headers
Idempotency requirements

Classification terminology

For clarity, the key words used to indicate the mandatory or optional expectations follows IETF Best Current Practice 14, namely:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14 [RFC2119] [RFC8174] when, and only when, they
appear in all capitals, as shown here.

Endpoints / resources

API endpoints are classified as "mandatory" or "optional" for an API Provider to implement. Within an endpoint, there may be functionality that is marked as mandatory or optional.

The following guidance applies:

Any endpoint or functionality that is listed is mandatory MUST be implemented by the API Provider, so it can be relied on by other Standards Users.
Any endpoint or functionality that is listed as optional MAY be implemented by the API Provider
API Providers MUST document and publish publicly the implemented endpoints and functionality
For Account Information APIs, if an API Provider does not implement an optional endpoint, the API Provider MUST return a 501 Not Implemented for any request made to that endpoint.
API Providers that implement optional endpoints MUST implement any mandatory sub-resources under those endpoints

API Request fields

API requests that contain a JSON data structure could contain fields that are listed as mandatory and optional. In some cases, the optional fields are conditionally required, however the conditional rules cannot easily be described in a data model or OpenAPI specification and so the specification text MUST be followed.

For clarity:

A Third Party MUST specify all mandatory fields in an API request. Failure to do so SHALL result in rejection by the API Provider.
A Third Party MAY specify optional fields in an API request.
A Third Party MAY specify an optional object, and MUST populate mandatory fields within that object
An API Provider MUST process all fields (mandatory and optional) sent by the Third Party.
An API Provider MAY reject any request that it cannot process, and MUST return appropriate errors in the standard error response structure.

API Response fields

API responses containing JSON data may include both mandatory and optional data. In some cases, optional fields may be conditionally required, however the conditional rules cannot easily be described in a data model or OpenAPI specification and so the specification text MUST be followed.

If the API Provider can supply optional data in API Response, then it is encouraged to do so in a manner reflecting data available in it's online/mobile banking. API Providers may choose to make additional information available beyond the minimum requirements, and MUST document and publicly publish this.

For clarity:

An API Provider MUST populate mandatory response fields
An API Provider MAY populate optional response fields.
API Providers MUST populate optional response fields in such way that matches what a customer would expect to see in the API Provider online/mobile banking channels.
If the optional response values are reflections of those supplied by the Third Party, the API Provider MUST NOT alter the values.

FAPI HTTP headers

Where specified, the relevant FAPI headers MUST be populated with appropriate values. See the general guidance on HTTP headers:

Query string parameters

Use of query string for pagination and filtering is mandatory for API Providers to implement but optional for Third Parties to use. If Third Parties do not use pagination and filtering this may restrict the data to which they have access. Filtering and pagination are considered to be good practice for large data volumes. Implementation and usage of pagination and filtering MUST follow guidance on the specification pages.

URI path parameters

Resource identifiers are present in URI path parameters and MUST follow the guidance in the the relevant specification pages.

Idempotency requirements

Idempotency is required for correct behaviour, and MUST be implemented when listed. The idempotency requirements may be found here:

https://paymentsnz.atlassian.net/wiki/spaces/PaymentsNZAPIStandards/pages/1669169167/NZ+Banking+Data+API+Specification+v2.3.2#Idempotency.1

Payments NZ API standards

Optional vs Mandatory