Leave a comment at the end of this page or email contact@krishagni.com
External App Messages API
- Vinayak Pawar
- 1 Purpose
- 2 General Characteristics
- 3 Workflow
- 4 Authentication
- 5 Send Messages
- 6 Logout
- 7 Errors
- 8 Examples
- 8.1 Sign-in
- 8.2 Sending Messages
- 8.3 Logout
- 9 Examples using cURL
- 9.1 Sign-in
- 9.2 Sending Messages
- 9.3 Sign-out
Purpose
The purpose of this document is to explain the APIs exposed by OpenSpecimen for consuming the external application messages. The external apps like the HL7 based system can submit their messages to OpenSpecimen APIs for patients, visits registration etc
General Characteristics
The APIs will be exposed over HTTPS endpoints using TLS 1.2/1.3 and secure ciphers.
Only authenticated and authorized users can invoke the respective APIs.
The APIs can be invoked only from whitelisted IP addresses.
Throttling will be implemented to avoid DDoS.
HSTS header will be enabled to ensure the API is accessed using only HTTPS.
Only JSON messages (request / response) will be exchanged between the client and OpenSpecimen.
Workflow
The typical workflow involves 3 steps a) Authentication b) Sending Messages and c) Logout as illustrated in the following chart:
Authentication
Sending applications can sign-in to OpenSpecimen by invoking the sessions API with valid credentials:
Method | POST |
Endpoint |
|
Headers | Content-Type: application/json
Accept: application/json |
Body | {
"loginName": <valid_login_name>,
"password": <secret_password>
} |
Response | HTTP 200 OK
Content-Type: application/json
Body:
{
"token": <session_token>
} |
The sending application will use an API user provisioned in the OpenSpecimen database. This will ensure the APIs can be invoked only from pre-determined, whitelisted IP addresses.
The login name and password of the API user will be shared with the sending application.
On successful authentication, the sending application will receive an HTTP 200 OK response along with an unique session token. The session token should be used in subsequent API calls to OpenSpecimen.
Send Messages
The sending applications can send one message at a time or send messages in a batch. The latter option is preferred, as it avoids the overhead involved with making HTTP requests. For example, the sending application can send messages in batches of 100. This is much faster/efficient than sending one message at a time.
Method | POST |
Endpoint |
|
Headers | |
Body | |
Response |
OpenSpecimen will accept all the messages and persist them in its local queue for processing. OpenSpecimen acknowledges the receipt of messages with an unique transaction ID.
The API will generate an error response only when the request body is malformed or the protocol is not recognised by OpenSpecimen.
The messages are processed by OpenSpecimen asynchronously. This means the sender will not be blocked for a long time. To put another way, the sender will be blocked only for the time required by OpenSpecimen to parse the incoming JSON message and persist in its local queue.
Logout
When the sending application is done with sending messages, it can invoke the signout/logout API to terminate the session with OpenSpecimen.
Method | DELETE |
Endpoint |
|
Headers | |
Body | |
Response |
After this the token can no longer be used for sending the messages.
Errors
All the client errors will be responded with HTTP 4xx response messages. The response body includes the actual error.
HTTP 401 | Invalid session token or no session token header |
HTTP 400 | Invalid input / request or malformed message |
Body |
All the OpenSpecimen related errors will be responded with HTTP 503 response messages.
Examples
Sign-in
Method | POST |
Endpoint |
|
Headers | |
Body | |
Response |
Sending Messages
Method | POST |
Endpoint |
|
Headers | |
Body | |
Response |
Logout
Method | DELETE |
Endpoint |
|
Headers | |
Body | |
Response |
Examples using cURL
Sign-in
Sending Messages
Sign-out
Leave a comment at the end of this page or email contact@krishagni.com