Follow naming
Naming matters. Further, make sure to stay true to specified data types. A string is not the same as an integer is not the same as a Boolean; and Incorrect naming, or field type will cause the request to be rejected or ignored.
Populate required fields
Required fields need to be present and have values different from null. In the Swagger documentation, the required fields are marked with an asterisk - see the recording below to understand better how to identify them. In certain cases depending on the content being passed additional fields may be required.
Specify existing references
In certain cases when calling an API endpoint you may be required to submit reference data that must first exist within the NikoHealth platform.
As an example prior to creating a patient via the API, a service location must exist within NikoHealth so that you are able to pass the Location ID you wish to associate the patient to.
Reference IDs can be returned using a GET API.
Reference IDs on a sandbox environment will be different than Reference IDs on a production environment so make sure to keep that in mind when developing your API integration.
Comply with HTTP and JSON Specifications
Data exchange format
When sending or receiving data from our service, you will be using HTTP to transfer the data and JSON as a data exchange format. When dealing with JSON payloads, your software should be fully compliant with the JSON specification according to ECMA-404.
Pay attention to :
Use true or false for the boolean field
Use . as a separator in case of decimal value
You don't need to explicitly pass null value for optional fields, feel free to omit them
Submit well-escaped string values
Date and time filters fields should follow ISO 8601 format
URIs and Content headers
Use properly formed URIs and query strings, which include URL-encoding query string parameters.
UTF-8 is a single content encoding used - consider it for both request and response data
NikoHealth APIs use JSON for data exchange - ensure you pass
Content-Type: application/jsonheader with every request and the code on your side expects it with every responseWith any serialization format (including URI query strings), understand that we will add fields to the response from time to time. Your code should be able to support the addition of data/fields in our response without breaking; that is one of the benefits of the JSON interchange format.
Use Secure Endpoints and Don't Ignore Security Warnings
Connect to our API securely (use HTTPS/TLS) and avoid using any plaintext endpoint. Do not ignore security warnings presented by your browser or your code libraries. Ignoring or disabling warnings may indicate TLS protocol version or cipher incompatibilities that must be resolved.
HTTP Methods and Responses
Follow the HTTP methods or verbs according to the documentation. If our documentation specifies a GET request, don't use another verb. Furthermore, don't match HTTP verbs with incompatible payloads. For example, don't submit HTTP body with a GET request—use a POST instead, as indicated in the documentation.
HTTP Status Codes
The request succeeded. The result meaning of "success" depends on the HTTP method:
GET: The resource has been fetched and transmitted in the message body.PUTorPOST: The resource describing the result of the action is transmitted in the message body.
The request succeeded, and a new resource was created as a result. This is typically the response sent after POST requests, or some PUT requests.
The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist.
The server has encountered a situation it does not know how to handle.
The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.
This error response is given when the server is acting as a gateway and cannot get a response in time.