Sending HL7 Messages to OpenSpecimen via API

1 Overview
2 Workflow
3 Authentication
4 Sending Messages
5 Logout
6 Error Handling
- 6.1 Error Response Format

Overview

This document provides details on how external applications can send HL7 messages to OpenSpecimen using its exposed APIs. The process involves authentication, message submission, and logout.

Workflow

Authentication: Obtain a session token.
Send Messages: Transmit HL7 messages in batch or individually.
Logout: Terminate the session.

Authentication

External applications must sign in to OpenSpecimen using the sessions API.

Descriptions	Values

Descriptions	Values
URL	`https://<HOSTNAME>/rest/ng/sessions`
Method	`POST`
Headers	`Content-Type: application/json Accept: application/json`
Request Body	`{ "loginName": "<valid_login_name>", "password": "<secret_password>" }`
Response	`{ "token": "<session_token>" }`

The session token must be included in subsequent API calls.

Sending Messages

Messages can be sent individually or in batches (preferred for efficiency).

Descriptions	Values

Descriptions	Values
URL	`https://<HOSTNAME>/rest/ng/external-app-messages`
Method	`POST`
Headers	`Content-Type: application/json Accept: application/json X-OS-API-CLIENT: <token_obtained_via_signin_api>`
Request Body	`{ "protocol": "HL7", "messages": [ { "message": "<HL7 message text AS IS>" }, { "message": "<HL7 message text AS IS>" } ] }`
Response	`{ "transactionId": "<unique_txn_id>" }`

Messages are queued asynchronously for processing. The API acknowledges receipt with a transaction ID.

Logout

Once message submission is complete, terminate the session.

Descriptions	Values

Descriptions	Values
URL	`https://<HOSTNAME>/rest/ng/external-app-messages`
Method	`DELETE`
Headers	`Content-Type: application/json Accept: application/json X-OS-API-CLIENT: <token_obtained_via_signin_api>`
Request Body	`{}`
Response	`{ "status": "success" }`

Error Handling

HTTP 401: Invalid or missing session token.
HTTP 400: Malformed request or input error.
HTTP 503: OpenSpecimen-related errors.

Error Response Format

[
  {
    "code": "<Error code>",
    "message": "<Human readable error message>"
  }
]

OpenSpecimen APIs