New Zealand MWS IG
1.1.5 - Release

New Zealand MWS IG - Local Development build (v1.1.5) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

## General

The following notes apply to all resources in this implementation.

### Resource representation: Json

Only Json is supported by this implementation.

### Errors

#### HTTP Error response codes

Status code | Description
--- | ---
400 | Bad Request
401 | The client needs to provide credentials, or has provided invalid credentials.
403 | Authentication was provided, but the authenticated user is not permitted to perform the requested operation.
404 | Resource not found
405 | HTTP method not allowed
409 | Resource conflict, the version provided for the resource is not the current version
413 | The request body was too big for the server to accept
422 | Unprocessable Entity, resource was rejected by the server because it “violated applicable FHIR profiles or server business rules”
500 | General system failure
429 | Exceeded quota

#### Response Body

The Response body may contain an OperationOutcome resource describing the result of the request message processing
The table below describes how the OperationOutcome should be populated

Field | Description | Cardinality
--- | --- | ---
OperationOutcome.issue |  | 0..n
OperationOutcome.issue[].severity | error | 0..1
OperationOutcome.issue[].code | processing | 0..1
OperationOutcome.issue[].details.coding.system | https://standards.digital.health.nz/ns/hip-error-code | 0..1
OperationOutcome.issue[].details.coding.code | See the HIP Error codes | 0..1
OperationOutcome.issue[].details.coding.display | See the HIP Error codes | 0..1
OperationOutcome.issue[].details.text | See indicative text on each operation use case | 0..1

#### Error Format

    {
        "resourceType": "OperationOutcome",
        "issue": [
            {
                "severity": "error",
                "code": "processing",
                "details": {
                    "coding": [
                        {
                            "system": "https://standards.digital.health.nz/ns/hip-error-code",
                            "code": "EM07201"
                            "display": "Missing a required field"
                        }
                    ],
                    "text": "Name is a required field"
                }
            }
        ]
    }

### Request Rules and Errors

- Request rules
  - Every request must include an:
    - http header item UserId that uniquely identifies the individual initiating the request.
    - OAuth 2 access token
    - An api-key
- Request errors
  - Authentication: missing userid header, HTTP401, Processing
  - Unauthorized, HTTP401
  - Forbidden, HTTP403

### HTTP Header Details

- This is a list of any additions to standard HTTP header protocol

### Request Headers

HTTP Header (Key) | HTTP Header (Value) | Description | Mandatory / Recommended / Optional
--- | --- | --- | ---
Authorization | Bearer {string} | The OAuth2 access token | Mandatory
userid | {string} | Client provided All requests for all resources must include an http header userid that uniquely identifies the individual initiating the request Preferably the hpi-person-id of the user would be provided if known, otherwise a userid that allows the authenticated organisation to identify the individual | Mandatory
X-Correlation-Id | {string} | Client provided All requests should contain a unique transaction id in the X-Correlation-Id field If present in the request this will be returned in the response, and can be used to track API calls Preferred less than 64 characters | Recommended
Content-Type | Application/json | Supported content type | Mandatory
x-api-key | {string} | Te Whatu Ora Provided – issued with client credentials | Mandatory

### Response Headers

Element name | Value | Description
--- | --- | ---
X-Correlation-Id | {string} | Returned if provided
X-request-Id | {string} | Unique identifier for the request within the NHI
ETag | {string} | The resource version number, returned on a Get

### Security

#### OAUTH2

The MWS server uses the OAUTH2 Client Credentials flow for authentication and authorisation and complies with the SMART specification for backend services

#### Scopes

See API for a description of the scopes required for each operation.

#### API Keys and Usage Plans

Clients will be emailed their API key, which should be treated as confidential information and not shared with other parties

An api-key associates the client with a usage plan, which sets upper limits on the API request volume which is permitted. If a client exceeds their usage plan allocation an http error will be returned

Clients will need to add their api key to the x-api-key header in each API request. If no API key is included in the request header, a “Forbidden” error will be returned

### Usage Plans

Plan | Rate | Burst | Quota
--- | --- | --- | ---
bronze | 1 request per second | 5 | 10,000 requests per day
silver | 5 requests per second | 25 | 250,000 requests per day
gold | 10 requests per second | 50 | 500,000 requests per day

All test accounts will be assigned to the bronze usage plan. If a Vendor wishes to be assigned to a higher plan, they should contact the Integration team via the General Enquiry form Please request a change to the usage plan and make sure you include the ClientID at minimum (AppId and Orgid also recommended).

Production accounts will be assigned to the silver usage plan. If an Organisation wishes to be assigned to the gold usage plan, they should contact the Te Whatu Ora NHI access team

If an application reaches its usage plan limit an HTTP 429 error will be returned. The expected behaviour is that the application will retry several times with an exponentially increasing delay

#### GEO Restriction

GEO Restriction rules prevent access from clients with IPs located in countries other than those listed below. If you need access from another country, please contact our team by completing the Enquiry form or adding a comment to the online onboarding request form if you have one.

- New Zealand
- Australia
- Canada
- Cook Islands