Message queue polling API
The polling API enables your systems to pull messages from the Haplo application. This is our recommended method, as it avoids the need for firewalls to be configured.
The queue information page will give you two URLs:
The Poll URL is used to fetch the unread messages from the queue. This includes a token, which is then POSTed to the Mark URL to mark the messages as read and ensure they are not sent again.
This two step process ensures that transport errors will not result in messages being lost.
Create an API key
The requests are authenticated with an API key. Click Create API key… on the queue information page.
To authenticate the request, use HTTP Basic authentication with the username haplo and the API key as the password.
Request unread messages
To fetch a small number of the oldest unread messages, you should make a simple authenticated GET request to the Poll URL. Here’s an example script using a curl command:
#!/bin/sh
set -e
API_KEY=01234567890123456789
SERVER=server.example.ac.uk
curl -X GET --user haplo:${API_KEY} https://${SERVER}/api/haplo-integration-messages/poll/QUEUE/fetch
Important: Replace QUEUE in the URL with the name of the queue. You can find the exact URL to use from queue information page.
To read all messages in a queue, repeat the requests to the poll and mark endpoints until the unreadCount is zero.
Mark messages as read
The response to the Poll URL will include a token. This must be posted back to the server to mark the messages received as read, so they will not be included the next time the application is polled.
The token is opaque and should not be interpreted by your integration code, as its format may change at any time.
Your integration should extract the token from the response, then POST to the Mark URL with the token as the token parameter. An example curl script is:
#!/bin/sh
set -e
API_KEY=01234567890123456789
SERVER=server.example.ac.uk
curl -X POST --data-urlencode "token=MSwy8w099=" --user haplo:${API_KEY} https://${SERVER}/api/haplo-integration-messages/poll/QUEUE/mark
Important: Replace QUEUE in the URL with the name of the queue. You can find the exact URL to use from queue information page.
The response to the Mark request will be JSON with the structure below:
{
"markedCount":2,
"unreadCount":1
}
Configuration for different environments
You will probably need to write your integration so that it can be used with test and live environments.
The only things which will differ between environments will be the hostname in the URLs and the API key.