Getting Started with the Transactional API

Overview

The Medicus Transactional API is organised around REST conventions and is designed to have a predictable URL structure. The API utilises many standard HTTP features, including methods (POST, GET) and error response codes. In all cases, JSON is returned as a response.

Medicus API endpoints are available over the internet via Hypertext Transfer Protocol Secure (HTTPS) and do not require consumers to have a presence (virtual or physical) on Medicus' infrastructure or VPN.
By design, REST is stateless and doesn’t require the existence of a user session.

Each Transactional API function can be accessed via the documented endpoints.

Medicus is a cloud-based application, therefore it is not necessary for consumer integration components to be installed within a healthcare organisation or on a user's workstation/PC.

API Conventions

URL Formation

All API endpoints are relative to the base URL, to which the endpoint paths are appended.
Each Medicus instance has its own tenantId, which forms part of the API URL subdomain.

For example https://{{tenantId}}.api.test.medicus.health .

URL Structure

From the API structure, it’s possible to derive the functional area that you are addressing.

a10001 - The Medicus tenant identifier. Each healthcare organisation has a unique tenant ID
api.test.medicus.health - The Medicus API environment & domain
/transactional-api - The type of API
/v1 - The version of the API schema
/patient - The type of record being referenced
/afff392a-5937-440d-8585-5397c217691f - The record identifiers
/journal - The functional area

An example of a fully formed URL:

https://a10001.api.test.medicus.health/transactional-api/v1/patient/afff392a-5937-440d-8585-5397c217691f/journal

API Schema Version

Versions of the API are referred to as a “schema version”. This is to ensure that any future changes and releases to the API are not confused with versions and releases of the core Medicus software.

Each major schema version is referenced in the URI (e.g. /v1). For example: /transactional-api/v1 represents schema version 1 of the Transactional API.

For more information about how we release different schema versions, please refer to the Release Process section below.

Is There a Delay Between the Data Received via the API and the Clinician’s System?

No, all data queried from the Medicus API is a real-time reflection of the data stored on the healthcare organisation’s staff-facing version of Medicus.

Under certain “race conditions”, where a user has just updated a record or taken action, the result of that action may not be reflected in the API output. This will happen if the API request was received immediately after the user action was completed.

Where appropriate, documents and records contain a date, time or dateTime stamp to inform you when the record was appended to Medicus.

How Do I Know Which Practice I Am Receiving Data From?

Each Medicus practice has a unique identifier, known as the tenantId. The tenantId is always the first part of the URL being queried.

For example: https://b10001.api.demo.medicus.health/transactional-api/v1/patient/afff392a-5937-440d-8585-5397c217691f/journal contains the tenantId of b10001

Please note: The healthcare organisation receiving the query remains the data controller for any data returned.

Best Practice

Idempotent Requests

Each POST request in the Medicus API supports idempotency keys to allow safely retrying a request without the risk of accidentally performing the same operation twice.

Requests are only confirmed as successful when the Medicus API responds with a HTTP 200 Ok response.

What is an Idempotency Key?

An idempotency key is a unique token that is submitted as part of the request header. The idempotency key guarantees that only one resource will be created, regardless of how many times a request is sent to the API endpoint.

How you create a key is up to you, but we recommend using V4 UUIDs, or another random string with enough entropy to avoid collisions.

How do I use Idempotency Keys with a Medicus API?

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to any POST request.

Example POST request:

JSON

Authorization: Bearer [token]
Idempotency-Key: 9f7f20c5-d420-48af-a2a7-f3ae60e6bda8

{
    "requestItems": [
        {
            "type": "prescription-reorder",
            "basedOnPrescriptionId": "08ebbbea-9c45-435e-9242-697ec2139891",
            "details": "A new prescription"
        },
        {
            "type": "prescription-issue",
            "prescriptionIssueId": "270b4c9f-847c-4a5e-a31f-63a5261aaadc"
        }
    ]
}
    "durationMinutes": 10
}

Releasing a New Schema Version

Breaking changes will always be a result of a change to the major schema version number. A breaking change constitutes a change to the API that is not backwards compatible.

A new schema version of the API will be reflected in the base URL of the endpoint (e.g. /v2).

In most cases, we’ll make sure previous schema versions of the API are available for use after a new schema version has been released. In the event that we need to depreciate an old schema version, we’ll follow the steps in the API deprecation section below.

Examples of breaking changes:

Removing or renaming an API resource endpoint or HTTP method
Removing or renaming enum values
Changing the visible behaviour of existing requests

How will I be Notified about Breaking Changes?

When we release a new schema version of the API, we’ll let you know by email and Slack.

For breaking changes, the notification will usually include:

The release date of the change
Instructions on how to upgrade your implementation
How to get additional support from Medicus, should you need it

All breaking changes will be documented in a new schema version of the API documentation.

API Deprecation

Periodically, we may need to deprecate old schema versions of the API. Whenever we deprecate a legacy schema version, we will always let you know. We will never deprecate a version without a newer version of the API being made available.

Notice of Deprecation

Medicus will give all registered consumers of the deprecated API at least 6 months' notice before the proposed end-of-life date.

As part of the deprecation process, we will provide guidance on:

Upgrading to current/replacement schema versions of the API
When to expect the deprecated API schema version to reach end-of-life
Support details to assist with migration to a newer schema version of the API
Changes to permissions or authentication

Further assistance can be provided to all consumers who have issues with the deprecation.

If we notice that you’re still using a legacy API a few months after we’ve been in contact, we may contact you individually to see if there’s anything we can do to help you with the upgrade.

When Something Goes Wrong

Outages or Processing Delays

We aim to perform all maintenance as a “live update” to minimise consumer impact and ensure that users and consumer systems can continue to operate during the maintenance activity.

We will inform all consumers ahead of time of any planned maintenance that may result in downtime.

In the unlikely event of an unforeseen outage, we will notify all registered API consumers of any unavailability or delays in processing. Registered consumers will be further notified upon system restoration.

Any systems outages and incident history will be reflected on the Medicus' Status Page.

Errors

Medicus uses conventional HTTP response codes to indicate the success or failure of an API request. Error states are restricted to the individual endpoint. An error state from a parallel or previous action will not be returned.

Errors are always returned with a HTTP response code and a JSON body that describes the error:

HTTP response code
An errors array:
- code (string) the Medicus error code
- title (string) the error's title
- detail (string) more detail about the error

Example response:

JSON

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errors": [
    {
      "code": "UNAUTHORISED"
      "title": "Unauthorised",
      "detail": "Unauthorised access. This has likely occurred as a result of an invalid authorisation header"
    }
  ]
}

We do not recommend parsing error messages to inform business logic within your application. Instead, you should rely on HTTP response codes and error codes.