People First API usage guide

This specification pertains to the MHR api JSON requests, some APIs support other content types for specific cases by they will not be covered here

Glossary

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 [RFC2119].

Headers

Accept

When requesting and the client is expecting a JSON response the client MUST have an accept header containing application/json.

Allow

This MUST be returned by the server on all responses to indicate what request methods are allowed at this URL. This MUST only contain values from the following list: GET, PUT, POST, DELETE, OPTIONS. The returning of OPTIONS is OPTIONAL.

Api version

The api-version header MAY be provided by the client when requesting a resource. This mechanism is in place to support breaking changes and backwards compatibility, when making a breaking change the api MUST increment the version number and support the existing resource for a time. When omitted the server MUST assume the client is requesting version 1. When the client request and non-existent version the server SHOULD return a 400 status code.

Authorization

When requesting a resource the client MAY pass an Authorization header. This MUST be a JWT token in the format Bearer {BASE64 encoded token}. This SHOULD be used by the server once validated as proof of identity for the request

Content-type

When sending JSON data both the client and server MUST have the Content-type header of application/json.

Environment code

This MAY be provided by the client to scope a request to a specific environment. Where this is omitted the server MUST assume the environment is the primary environment for the provided tenant code.

ETag

This SHOULD be returned by the server on all responses. This is a hash of the current state of the requested resource, the client SHOULD then pass this value in the If-Match header to validate they are updating the most recent version of the resource

If-Match

SHOULD be provided by clients when updating a resource, the server SHOULD then check this value against the current resource. In the case where these do not match the server MUST return a 412 precondition failed error.

Tenant code

This MUST be provided by the client to scope a request to a specific tenant.

URL Paths

URL paths SHOULD be lowercase. Path parts SHOULD be nouns rather than verbs. Any names within the path SHOULD NOT use abbreviations. Where the resource behind the URL is a collection the name SHOULD be plural (e.g. people/{id}). Where the resource is a singular item it SHOULD be singular (e.g. people/{id}/photo).