Developer Documentation: openIMIS Subscription API

This document provides a guide for developers to programmatically create and manage resource subscriptions using the openIMIS backend's REST API. All examples use curl, a universal command-line tool for making HTTP requests.

The openIMIS Subscription API allows external applications to be notified via a webhook when a specific FHIR resource (e.g., Claim) is created or updated.

All API requests require authentication. The process involves two steps:

1. Login: Send a POST request with a username and password to the /login endpoint to receive a temporary JSON Web Token (JWT).

2. Authenticated Request: Include this JWT as a Bearer Token in the Authorization header of all subsequent API calls.

First, you must authenticate to get a JWT. This token is required for all other API calls.

Endpoint: POST /api/api_fhir_r4/login/

Request:

• Method: POST

• URL: The base URL of your openIMIS instance followed by /api/api_fhir_r4/login/.

• Headers:

  • Content-Type: application/json: Indicates that the request body is in JSON format.

• Body: A JSON object containing the username and password for a valid openIMIS user.

Successful Response (200 OK):

The server will respond with a JSON object containing the token.

To start receiving notifications, you must create a subscription resource on the server.

Endpoint: POST /api/api_fhir_r4/Subscription/

Request:

Request Breakdown:

• Method: POST

• URL: The base URL followed by /api/api_fhir_r4/Subscription/.

• Headers:

  • Authorization: Bearer <YOUR_TOKEN>: This is mandatory. It proves you have the right to create a subscription.

  • Content-Type: application/json: Specifies the body format.

• Body (JSON Payload):

  • resourceType: Must be "Subscription".

  • status: Must be "active" to start receiving notifications. Other options might include "requested" or "off".

  • end: (Optional, but recommended) An ISO 8601 timestamp for when the subscription should automatically expire.

  • reason: A human-readable string explaining the purpose of this subscription.

  • criteria: (Crucial) A string specifying the FHIR resource to monitor. Examples: "Claim", "Patient", "Coverage", "Insuree".

  • channel: An object describing how notifications should be delivered.

    • type: Must be "rest-hook" for webhook notifications.

    • endpoint: (Crucial) The full, publicly accessible URL where your client application is listening for POST requests. The openIMIS server must be able to reach this URL.

      • For production, this must be a public internet URL (e.g., https://api.your-app.com/webhook).

    • header: An array of strings defining headers to be sent with the webhook notification. The specific format ["{\"Key\": \"Value\"}"] (a list containing one stringified JSON object) may be required by the backend.

Successful Response (201 Created):

The server will respond with the full subscription resource it just created, including a server-generated id.

When you no longer wish to receive notifications, you should delete the subscription resource from the server. Based on the backend implementation, this is done via a DELETE request.

Endpoint: DELETE /api/api_fhir_r4/Subscription/{id}/

Request:

Request Breakdown:

• Method: DELETE

• URL: The URL must include the unique id of the subscription you want to remove.

• Headers:

  • Authorization: Bearer <YOUR_TOKEN>: Mandatory for authentication.

• Body: A DELETE request does not have a body.

Successful Response (204 No Content):

A successful deletion will typically return a 204 No Content status code. This means the operation succeeded, and there is no data to return in the response body.

Once a subscription is active, any creation or update of a resource matching the criteria will cause the openIMIS server to send an HTTP POST request to the endpoint URL you specified.

• Method: POST

• Headers: The headers will include what you defined in the channel.header array (e.g., Content-Type: application/json).

• Body: The body will contain a FHIR resource representing the notification event. This often includes a link to the resource that was updated.

Client application at the endpoint URL must be prepared to:

1. Accept POST requests.

2. Parse the JSON body of the request.

3. Return a 2xx (e.g., 200 OK or 204 No Content) status code promptly to acknowledge receipt. If the server receives a non-2xx status, it may retry sending the notification.

4.1. The subscriber will receive following response in a callback url:

Demo of subscription process using mock application

Mock simulated app

sandbox/mock_claim_subscription at develop · openimis/sandbox