Example HealthBus REST API calls

Phillip Odam

Modified on: Thu, 18 Mar, 2021 at 5:23 PM

The following examples are using a REST client library sourced from http://kong.github.io/unirest-java/. The unirest library is available in Java, Javascript, Ruby, PHP, Python & Objective-C, so chances are the library is available for the language you are developing in. While unirest is available for .NET, we currently recommend http://restsharp.org/ for .NET development. The .NET version of unirest does not currently include all the required features for integrating with the HealthBus REST API. If you are interested in code samples using restsharp please feel free to contact us.

NOTE: RestSharp is provided as a NuGet package, to consume RestSharp in Visual Studio please see this Microsoft article https://www.visualstudio.com/en-us/docs/package/nuget/consume.

For details on how to include, test or use the library in your project please refer to the unirest web site.

Please note the HealthBus services are operated in Production and Test environments. To ensure you are in the correct environment, all you need to change is

	Production	Test
hostname	api.direct.hispdirect.com api.rosettahealth.net healthbus.rosettahealth.net	api.rosettahealth.net
credentials	usernames and passwords are not shared between environments

The following code snippets show how to use the unirest Java library to call each of the endpoints provided by the HealthBus REST API. Minor adjustments to the following examples will produce working examples in each of the other languages that unirest supports.

If you are looking for more complete examples please see some of the common use cases we have written up.

Message Management REST API calls

// Retrieve a Bus message

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/MailManagement/ws/v3/retrieve/message")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide address and password
                  .queryString("messageID", "") // provide required message ID
                  .queryString("from", "") // provide required from address
                  .asJson();
JsonNode json = response.getBody(); // json response

// Retrieve a raw Bus message

HttpResponse<Object> response = Unirest.get("https://api.rosettahealth.net/MailManagement/ws/v3/retrieve/message/raw")
                  .basicAuth("username", "password") // provide address and password
                  .queryString("messageID", "") // provide required message ID
                  .queryString("from", ""); // provide required from address
InputStream is = response.getRawBody(); // raw message

// Retrieve an attachment

HttpResponse<Object> response = Unirest.get("https://api.rosettahealth.net/MailManagement/ws/v3/retrieve/message/attachment")
                  .basicAuth("username", "password") // provide address and password
                  .queryString("messageID", "") // provide required message ID
                  .queryString("from", "") // provide required from address
                  .queryString("attachmentID", ""); // provide required attachment ID
InputStream is = response.getRawBody(); // attachment

In most cases the Retrieve message listing is not the REST API call you want, you should instead call the notification service

// Retrieve a message listing on a queue inbox

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/MailManagement/ws/v3/retrieve/message/list")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide address and password
                  .queryString("offset", "0") // provide message list offset
                  .queryString("length", "10") // provide message list length
                  .asJson();
JsonNode json = response.getBody(); // json response

// Send a HealthBus message

HttpResponse<JsonNode> response = Unirest.put("https://api.rosettahealth.net/MailManagement/ws/v3/send/message")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide address and password
                  .field("to", "") // provide required recipient address
                  .field("subject", "") // provide required message subject
                  .field("body", "") // provide required message body
                  .asJson();
JsonNode json = response.getBody(); // json response

// Upload an attachment

HttpResponse<JsonNode> response = Unirest.put("https://api.rosettahealth.net/MailManagement/ws/v3/send/message/attachment")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide address and password
                  .field("attachment", new File("")) // provide file to upload
                  .asJson();
JsonNode json = response.getBody(); // json response

// Send a HealthBus message with attachment

HttpResponse<JsonNode> response = Unirest.put("https://api.rosettahealth.net/MailManagement/ws/v3/send/message")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide address and password
                  .field("to", "") // provide required recipient address
                  .field("subject", "") // provide required message subject
                  .field("body", "") // provide required message body
                  .field("attachmentId", "") // provide attachment id returned when uploading attachment
                  .asJson();
JsonNode json = response.getBody(); // json response

// Remove a HealthBus message

HttpResponse<JsonNode> response = Unirest.delete("https://api.rosettahealth.net/MailManagement/ws/v3/remove/message")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide address and password
                  .queryString("messageID", "") // provide required message ID
                  .queryString("from", "") // provide required from address
                  .asJson();
JsonNode json = response.getBody(); // json response

Account Management REST API calls

// Create a HealthBus addressable inbox

HttpResponse<JsonNode> response = Unirest.put("https://api.rosettahealth.net/AccountManagement/ws/v2/mail/{address}")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .routeParam("address", "") // provide address to create
                  .field("new_password", "") // provide password for address
                  .asJson();
JsonNode json = response.getBody(); // json response

// Update a HealthBus address

HttpResponse<JsonNode> response = Unirest.post("https://api.rosettahealth.net/AccountManagement/ws/v2/mail/{address}")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .routeParam("address", "") // provide address to update
                  .field("new_password", "") // provide password for address
                  .asJson();
JsonNode json = response.getBody(); // json response

// Check existence of a HealthBus address

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/AccountManagement/ws/v2/mail/{address}")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .routeParam("address", "") // provide address to check
                  .asJson();
JsonNode json = response.getBody(); // json response

// Remove a HealthBus address

HttpResponse<JsonNode> response = Unirest.delete("https://api.rosettahealth.net/AccountManagement/ws/v2/mail/{address}")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .routeParam("address", "") // provide address to delete
                  .asJson();
JsonNode json = response.getBody(); // json response

// Alter notifications for individual address

HttpResponse<JsonNode> response = Unirest.post("https://api.rosettahealth.net/AccountManagement/ws/v2/notify/individual/{address}")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .routeParam("address", "") // provide address to add a notification to
                  .field("add_email_notification", "") // provide Email address
                  .asJson();
JsonNode json = response.getBody(); // json response

// Check on notifications for individual address

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/AccountManagement/ws/v2/notify/individual/{address}")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .routeParam("address", "") // provide address to add a notification to
                  .asJson();
JsonNode json = response.getBody(); // json response

// Create an admin account

HttpResponse<JsonNode> response = Unirest.put("https://api.rosettahealth.net/AccountManagement/ws/v2/domain/admin/{adminname}/FACILITY")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Domain Admin username and password
                  .routeParam("adminname", "") // provide Facility Admin username to create
                  .field("password", "") // provide Facility Admin password
                  .asJson();
JsonNode json = response.getBody(); // json response

// Update an admin account

HttpResponse<JsonNode> response = Unirest.post("https://api.rosettahealth.net/AccountManagement/ws/v2/domain/admin/{adminname}/FACILITY")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Domain Admin username and password
                  .routeParam("adminname", "") // provide Facility Admin username to update
                  .field("password", "") // provide Facility Admin password
                  .asJson();
JsonNode json = response.getBody(); // json response

// Check an admin account

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/AccountManagement/ws/v2/domain/admin/{adminname}/FACILITY")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Domain Admin username and password
                  .routeParam("adminname", "") // provide Facility Admin username to check
                  .asJson();
JsonNode json = response.getBody(); // json response

// Remove an admin account

HttpResponse<JsonNode> response = Unirest.delete("https://api.rosettahealth.net/AccountManagement/ws/v2/domain/admin/{adminname}/FACILITY")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Domain Admin username and password
                  .routeParam("adminname", "") // provide Facility Admin username to remove
                  .asJson();
JsonNode json = response.getBody(); // json response

// Get account listing as Domain Admin

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/AccountManagement/ws/v2/domain/list/admin")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Domain Admin username and password
                  .asJson();
JsonNode json = response.getBody(); // json response

// Get account listing as Facility Admin

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/AccountManagement/ws/v2/list/mail")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Facility Admin username and password
                  .asJson();
JsonNode json = response.getBody(); // json response

// Poll for new message notifications across an entire domain

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/AccountManagement/ws/v2/notify/organization")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .queryString("domain", "") // provide domain to retrieve notifications for
                  .asJson();
JsonNode json = response.getBody(); // json response

// Poll for new message notifications for a particular address

HttpResponse<JsonNode> response = Unirest.get("https://api.rosettahealth.net/AccountManagement/ws/v2/notify/organization")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .queryString("email", "") // provide address to retrieve notifications for
                  .asJson();
JsonNode json = response.getBody(); // json response

Related Articles