Quercus Message Link Developer’s Guide<>

Quercus Message Link – RESTful web services

Quercus Message Link – RESTful web services

Quercus Message Link REST web services allow developer to retrieve and post event driven XML messages from Quercus quickly and easily using standard REST (Representational State Transfer) techniques.

Quercus Message Link RESTful web services provides:

the ability to send, receive and delete messages in Quercus message queues

an optional two-stage acknowledgement process that ensures messages that are received by the user are not deleted until a receipt acknowledgement is returned to Quercus

a consistent interface to all existing and future message link services

secure exchange of data between disparate systems

fast performance

The following chapters show you how to access and configure the Message Link REST web services. The following areas are covered:

the Ping, Send, Receive and Delete functions available in the web service

the security available to the web services

the Quercus Message Link Scratchpad which is a test rig for the web services

The guide does not provide details of REST implementation techniques as these are dependent upon the specifics of your web development platform.

What is REST?

REST is an acronym for Representation Status Transfer.

Wikipedia defines REST as “a style of software architecture for distributed hypermedia systems such as the World Wide Web”.

http://en.wikipedia.org/wiki/Representational_State_Transfer

REST in practice

In practical terms, the important feature of REST implementations is the return of machine‑parsable structured data (usually in the form of an XML document) in response to a standard HTTP GET or POST request. The data which is returned depends upon the construction of the URL sent as part of the request. Common REST addressing techniques are:

map the data to a URL and then use sub-paths of the URL to allow the retrieval of subsets of the full data set (e.g.http://mycollege.org/services/arts/2011)

map the data to a URL and then use parameters to allow the retrieval of subsets of the full data set (e.g.http://mycollege.org/services?faculty=arts&year=2011)

Quercus Message Link uses the modification-with-parameters technique as it is better suited to the relational Quercus data. An example of a Message Link URL is shown below:

https://labs.campusit.net/qdev/qml_rest.ReceiveMessage?accessid=DEVELOP

What messages can I access through Message Link web services?

You can dequeue (receive), enqueue (send), delete and review the status of a message, provided they are enabled, to/from the Quercus message queues. There are seven service calls allowed:

Ping

This service simply identifies whether or not the message link web service is active.

SendMessage

This service allows the user to enqueue a message to the MESSAGE_IN queue so it can be consumed by Quercus Message Link.

GetMessageStatus

This service allows the user to check the status of any inbound message that has been sent to the messaging service.

ReceiveMessage

This service dequeues the next message in the MESSAGE_OUT queue table and responds with the message in its payload.

DeleteMessage

This service allows users to delete a specific message from the MESSAGE_OUT queue table. The response from this service is a success or error response.

ReceiveHospital

This service dequeues a message from the HOSPITAL queue table so messages that have been rejected due to errors can be inspected.

DeleteHospital

This service allows users to delete a specific message from the HOSPITAL queue. The response from this service is a success or error response.