Online MQ API
From Online MQ
Contents |
OnlineMQ Web Services
General
OnlineMQ offers the following web service protocols:
- Plain Old XML (POX or HTTP/XML)
- SOAP (RPC)
- REST
But first please take the time to examine our Resources (since we have a Resource Oriented Architecture). It will help you understand the general architecture of the web services and actions that are allowed.
All web services are implemented as stateless actions. The HTTP connections can be initiated through any web service action and can optionally be kept alive between actions for reducing SSL and connection overhead. Keeping the connection alive will not result in any functional application state maintaining.
Web service Protocols
POX
The Plain Old XML (POX or HTTP/XML) interface uses a generic canonical XML structure for all requests and responses.
This web service is reachable through the following url (port 443 for https, port 80 for http):
https://mq.onlinemq.com/webservice_pox_v1
It is stateless web service with a synchronous request-response flow. The TCP/IP with SSL encryption can be left open between subsequent requests (this may help reduce some of the SSL connection overhead), but the web service will be stateless and will thus not rely on any HTTP session identifiers.
All requests must be send through a HTTP POST request, with the following headers:
Content-Type: application/xml Accepts: application/xml
The XML payload of the requests and the responses always has the same generic canonical structure (in which all elements are optional). This way a specific data field can always be found at the same location in the XML and is always addressable with the same xpath.
The response of an action will always have an error code in the /onlinemq/status/error_code field. If this error code is zero, the action was performed successfully. If not a non-zero value will be return with an error description. See the possible error codes and descriptions in the following chapter.
All requests will require authentication, because the web service is stateless.
common requirements for all requests
- XML must be a subset of the canonical
- The request XML does not care about the order of elements, only the nesting is relevant.
- The onlinemq/header/version field must have the value ’1.0’
- The onlinemq/header/action field must contain the action you want to perform
- The onlinemq/authentication/login field must contain a login name
- The onlinemq/authentication/password field must contain the password for the login name
Used fields for request and response of all actions
| o
p e n _ c o n n e c t i o n | c
h e c k _ c o n n e c t i o n | c
l o s e _ c o n n e c t i o n | p
e e k _ m e s s a g e | r
e c e i v e _ m e s s a g e | s
e n d _ m e s s a g e | d
e l e t e _ m e s s a g e | l
i s t _ q u e u e _ d e f i n i t i o n s | s
h o w _ q u e u e _ d e f i n i t i o n | c
r e a t e _ q u e u e _ d e f i n i t i o n | u
p d a t e _ q u e u e _ d e f i n i t i o n | d
e l e t e _ q u e u e _ d e f i n i t i o n | e
m p t y _ q u e u e _ d e f i n i t i o n | l
i s t _ q u e u e _ m a n a g e r s | s
h o w _ q u e u e _ m a n a g e r | c
r e a t e _ q u e u e _ m a n a g e r | u
p d a t e _ q u e u e _ m a n a g e r | d
e l e t e _ q u e u e _ m a n a g e r | l
i s t _ b o d y _ t y p e s | l
i s t _ b o d y _ e n c o d i n g s | |
| XPATH canonical representation of request | ||||||||||||||||||||
| /onlinemq/header/version | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M |
| /onlinemq/header/created_at | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a |
| /onlinemq/header/action | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M |
| /onlinemq/status/error_code | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a |
| /onlinemq/status/error_description | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a |
| /onlinemq/authentication/login | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M |
| /onlinemq/authentication/password | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M | M |
| /onlinemq/authentication/email | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a | a |
| /onlinemq/transaction/id | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/transaction/number_of_messages | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/id | - | O | - | R | R | R | R | R | R | R | R | R | R | - | R | a | R | R | - | - |
| /onlinemq/queue_manager/name | - | O | - | R | R | R | R | R | R | R | R | R | R | - | R | M | R | R | - | - |
| /onlinemq/queue_manager/description | - | - | - | a | a | a | a | a | a | a | a | a | a | - | a | O | O | a | - | - |
| /onlinemq/queue_manager/enabled | - | - | - | a | a | a | a | a | a | a | a | a | a | - | a | O | O | a | - | - |
| /onlinemq/queue_manager/queue_definition/id | - | O | - | R | R | R | R | - | R | a | R | R | R | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/name | - | O | - | R | R | R | R | - | R | M | R | R | R | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/type | - | - | - | a | a | a | a | - | a | O | a | a | a | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/description | - | - | - | a | a | a | a | - | a | O | O | a | a | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/visibility_timeout | - | - | - | a | a | a | a | - | a | O | O | a | a | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/max_depth | - | - | - | a | a | a | a | - | a | O | O | a | a | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/depth | - | - | - | a | a | a | a | - | a | a | a | a | a | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/send_enabled | - | - | - | a | a | a | a | - | a | O | O | a | a | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/receive_enabled | - | - | - | a | a | a | a | - | a | O | O | a | a | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/message/id | - | - | - | O | O | a | M | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/message/sender | - | - | - | a | a | a | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/message/priority | - | - | - | a | a | O | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/message/body_type/id | - | - | - | a | a | O | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/message/body_type/name | - | - | - | a | a | O | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/message/body_encoding/id | - | - | - | O | O | O | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/message/body_encoding/name | - | - | - | O | O | O | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definition/message/body | - | - | - | a | a | M | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/id | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/name | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/type | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/description | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/visibility_timeout | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/max_depth | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/depth | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/send_enabled | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_manager/queue_definitions/item/receive_enabled | - | - | - | - | - | - | - | a | - | - | - | - | - | - | - | - | - | - | - | - |
| /onlinemq/queue_managers/item/id | - | - | - | - | - | - | - | - | - | - | - | - | - | a | - | - | - | - | - | - |
| /onlinemq/queue_managers/item/name | - | - | - | - | - | - | - | - | - | - | - | - | - | a | - | - | - | - | - | - |
| /onlinemq/queue_managers/item/description | - | - | - | - | - | - | - | - | - | - | - | - | - | a | - | - | - | - | - | - |
| /onlinemq/queue_managers/item/enabled | - | - | - | - | - | - | - | - | - | - | - | - | - | a | - | - | - | - | - | - |
| /onlinemq/body_types/item/id | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | a | - |
| /onlinemq/body_types/item/name | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | a | - |
| /onlinemq/body_encodings/item/id | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | a |
| /onlinemq/body_encodings/item/name | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | a |
| Legend | ||
| M | mandatory for request and returned in response | |
| O | optional for request and returned in response | |
| R | special: either id or name is mandatory | |
| a | ignored on request and add in response (if available) | |
| - | ignored on request and not added in response | |
Examples
Since OnlineMQ is developed using a Test Driven Development approach there is an extensive set of example messages to examine for help. See our Sample Code
SOAP
The SOAP (RPC) interface of OnlineMQ is basically the same as the POX interface, only with the SOAP (RPC) specific envelopes and endpoints.
Because SOAP already has a specific enveloping for each action, the action field in the canonical is ignored for the requests. It is returned in the response, but can be ignored.
A WSDL is available at
https://mq.onlinemq.com/webservice_soap_v1/wsdl
For further documentation, see the POX interface description.
REST
The RESTful interface is a lightweight and stateless web service with a synchronous request-response flow. The TCP/IP with SSL encryption can be left open between subsequent requests (this may help reduce some of the SSL connection overhead), but the web service will be stateless and will thus not rely on any HTTP session identifiers.
All requests must be send through a HTTP request, with the following headers:
Content-Type: application/xml
Accepts: application/xml
Optionally the Accepts header can be omitted if the URL is postfixed by ".xml".
The RESTful web service will have a different URL endpoint for each resource. We will use the convention of the singular form for the resource and the plural form for the URL endpoint.
The allowed HTTP methods are GET, POST, PUT and DELETE. If your implementation does not allow PUT and DELETE actions, these can be faked by adding a fake method parameter in the request: "_method=put". This parameter must be in the query string of the URL, i.e.
https://mq.onlinemq.com/queue_managers?_method=put
In contrast to the POX and SOAP interfaces (which use XML nesting to express the parent/child relationships and references), the relationship between the resources is simply stored in an id referencing attribute. Also since the RESTful interface is fully based on the concept of resources, the id will be the only allowed identifier of a resource (in contrast the identification by name in POX and SOAP).
Authentication for the RESTful web service is done through HTTP Basic Access Authentication (use SSL for security).
In case of errors the HTTP status is set accordingly (see Error handling). In addition the response body will contain the following XML:
<errors> <error>Error description: error code 100</error> ... </errors>
The body of the error element can be parsed for the error code by taking the last 3 digits.
Resource: Queue Manager
singular: queue_manager
plural: queue_managers
base url: /queue_managers
nesting: none.
special: on create the account_id is not mandatory since it is defaulted by the current user account.
Singular XML
<?xml version="1.0" encoding="UTF-8"?> <queue_manager> <account_id type="integer">1</account_id> <description>Default queue manager</description> <enabled type="boolean">true</enabled> <id type="integer">1</id> <name>default</name> <queue_manager>
Plural XML
<?xml version="1.0" encoding="UTF-8"?>
<queue_managers type=”array”>
<queue_manager>
...
</queue_manager>
...
<queue_managers>
Endpoints
| Model Request | HTTP Method | URI | Request body | Response (on success) |
| show_queue_manager | GET | /queue_managers/<id> | N/A | Status: 200 OK singular XML |
| update_queue_manager | PUT | /queue_managers/<id> | singular XML | Status: 200 OK |
| create_queue_manager | POST | /queue_managers | singular XML | Status 201: Created Location: /queue_managers/<id> |
| delete_queue_manager | DELETE | /queue_managers/<id> | N/A | Status: 200 OK |
| list_queue_managers | GET | /queue_managers | N/A | Status: 200 OK plural XML |
Resource: Queue Definition
singular: queue_definition or queue_forwarder_definition
plural: queue_definitions
base url: /queue_managers/<queue_manager_id>/queue_definitions OR /queue_definitions/<id>
nesting: always allowed inside queue_managers. Optionally direct when queue_definition id can be provided.
special: on create the queue_manager_id attribute is not mandatory since it is already in the URL.
Singular XML
<?xml version="1.0" encoding="UTF-8"?> <queue_definition> <description>This is the development queue for new orders</description> <id type="integer">1</id> <max_depth type="integer" nil="true"></max_depth> <max_message_length type="integer" nil="true"></max_message_length> <name>dev.orders.new</name> <queue_manager_id type="integer">1</queue_manager_id> <receive_enabled type="boolean">true</receive_enabled> <send_enabled type="boolean">true</send_enabled> <visibility_timeout type="integer">5</visibility_timeout> <depth type="integer">8</depth> </queue_definition>
The type of the queue is expressed by the root tag of the singular XML: <queue_definition> or <queue_forwarder_definition>
The plural XML root element is always <queue_definitions>, since it is the base type.
Plural XML
<?xml version="1.0" encoding="UTF-8"?>
<queue_definitions type=”array”>
<queue_definition>
...
</queue_definition>
<queue_forwarder_definition>
...
</queue_forwarder_definition>
...
<queue_definitions>
Endpoints
| Model Request | HTTP Method | URI | Request body | Response (on success) |
| show_queue_definition | GET | /queue_definitions/<id> | N/A | Status: 200 OK singular XML |
| update_queue_definition | PUT | /queue_definitions/<id> | singular XML | Status: 200 OK |
| create_queue_definition | POST | /queue_managers/<queue_manager_id>/queue_definitions | singular XML | Status 201: Created Location: /queue_definitions/<id> |
| delete_queue_definition | DELETE | /queue_definitions/<id> | N/A | Status: 200 OK |
| list_queue_definitions | GET | /queue_managers/<queue_manager_id>/queue_definitions | N/A | Status: 200 OK plural XML |
| empty_queue_definition | POST | /queue_definitions/<id>/empty | N/A | Status: 200 OK |
Resource: Message
singular: message
plural: messages
base url: /queue_definitions/<queue_definition_id>/messages
nesting: always inside queue_definitions. This is done because the queue implementation can vary allowing direct references to messages or not.
special: On create the queue_definition_id attribute is overruled by the queue_definition_id of the URL, the queue_definition_id attribute is therefore non mandatory in the request.
Singular XML
<?xml version="1.0" encoding="UTF-8"?> <message> <id type="integer">27</id> <queue_definition_id type="integer">1</queue_definition_id> <sender>bas</sender> <priority type="integer">0</priority> <body_type_id type="integer">6</body_type_id> <body_encoding_id type="integer">1</body_encoding_id> <body>normal message body with in UTF-8 encoding</body> </message>
Plural XML: non existing
Endpoints
| Model Request | HTTP Method | URI | Request body | Response (on success) | Optional query arguments |
| send_message | POST | /queue_definitions/<queue_definition_id>/messages | singular XML | Status 201: Created Location: /queue_definitions/<queue_id>/messages/<id> | |
| peek_message (FIFO & priority) | GET | /queue_definitions/<queue_definition_id>/messages/peek | N/A | Status: 200 OK singular XML | body_encoding_id: integer |
| peek_message (with id) | GET | /queue_definitions/<queue_definition_id>/messages/<id>/peek | N/A | Status: 200 OK singular XML | body_encoding_id: integer |
| receive_message (FIFO & priority) | POST | /queue_definitions/<queue_definition_id>/messages/receive | N/A | Status: 200 OK singular XML | body_encoding_id: integer |
| receive_message (with id) | POST | /queue_definitions/<queue_definition_id>/messages/<id>/receive | N/A | Status: 200 OK singular XML | body_encoding_id: integer |
| delete_message | DELETE | /queue_definitions/<queue_definition_id>/messages/<id> | N/A | Status: 200 OK |
Example, request with specified body encoding in CDATA:
GET /queue_definitions/<queue_id>/messages/peek?body_encoding_id=2
<?xml version="1.0" encoding="UTF-8"?> <message> <id type="integer">27</id> <queue_definition_id type="integer">1</queue_definition_id> <sender>bas</sender> <priority type="integer">0</priority> <body_type_id type="integer">6</body_type_id> <body_encoding_id type="integer">1</body_encoding_id> <body><![CDATA[normal message body with in CDATA encoding]]></body> </message>
Resource: Body Type
singular: body_type
plural: body_types
base url: /body_types
nesting: none.
special: body types are a read only resource.
Singular XML
<?xml version="1.0" encoding="UTF-8"?> <body_type> <id type="integer">1</id> <name>XML</name> </body_type>
Plural XML
<?xml version="1.0" encoding="UTF-8"?>
<body_types type="array">
<body_type>
...
</body_type>
...
</body_types>
Endpoints
| Model Request | HTTP Method | URI | Request body | Response (on success) |
| show_body_type | GET | /body_types/<id> | N/A | Status: 200 OK singular XML |
| list_body_types | GET | /body_types | N/A | Status: 200 OK plural XML |
Resource: Body Encoding
singular: body_encoding
plural: body_encodings
base url: /body_encodings
nesting: none.
special: body encodings are a read only resource.
Singular XML
<?xml version="1.0" encoding="UTF-8"?> <body_encoding> <id type="integer">1</id> <name>XML</name> </body_encoding>
Plural XML
<?xml version="1.0" encoding="UTF-8"?>
<body_encodings type="array">
<body_encoding>
...
</body_encoding>
...
</body_encodings>
Endpoints
| Model Request | HTTP Method | URI | Request body | Response (on success) |
| show_body_encoding | GET | /body_encodings/<id> | N/A | Status: 200 OK singular XML |
| list_body_encodings | GET | /body_encodings | N/A | Status: 200 OK plural XML |
Error handling
All error situations have been assigned an error code.
For the POX and SOAP web services the error code is communicated in the canonical XML structure, with a HTTP status code of 200 (so HTTP status codes are meaningless for these web services).
For RESTful web services the error codes are communicated is the response body and a (less distinct) HTTP status code is also set.
HTTP status code mapping for RESTful interfaces:
| Valid response, no exception |
| Bad request |
| Unauthorized |
| Resource not found |
| Conflict |
| Invalid resource |
| Server error |
See error list for complete reference:
| error code | description | HTTP status |
| 000 success | ||
| 0 | OK | 200 |
| 100 general errors | ||
| 100 | Unknown action for /onlinemq/header/action | 400 |
| 101 | Authentication failed | 401 |
| 102 | Invalid XML | 400 |
| 103 | Invalid XML version | 400 |
| 200 queue & queue manager errors | ||
| 201 | Unknown queue | 404 |
| 202 | Unknown queue for specified queue manager | 404 |
| 203 | Unknown queue manager | 404 |
| 204 | User is not authorized as viewer for queue | 401 |
| 205 | User is not authorized as moderator for queue | 401 |
| 206 | Queue can not be deleted because it must be empty | 409 |
| 207 | Queue name is already taken for this queue manager | 409 |
| 208 | Queue name can not be blank | 422 |
| 209 | Queue with the same name already exists for this queue manager | 422 |
| 210 | Queue can not be emptied because one or more messages are in a transaction | 409 |
| 211 | User is not authorized as viewer for queue manager | 401 |
| 212 | User is not authorized as moderator for queue manager | 401 |
| 213 | Queue manager name can not be blank | 422 |
| 214 | Queue manager name is already taken | 422 |
| 215 | Queue manager can not be deleted because it still has queues | 409 |
| 216 | Queue is disabled for sending | 409 |
| 217 | Queue is disabled for receiving | 409 |
| 218 | Queue manager is disabled | 409 |
| 219 | Queue manager name can not exceed 20 characters | 422 |
| 220 | Queue manager name can only contain [a-Z][0-9]_-. | 422 |
| 221 | Queue name can not exceed 20 characters | 422 |
| 222 | Queue name can only contain [a-Z][0-9]_-. | 422 |
| 223 | This action is not allowed for a forwarding queue | 409 |
| 224 | One or more destination queues are disabled for sending | 409 |
| 225 | One or more destination queue managers are disabled | 409 |
| 226 | Circular queue forwarding references are not allowed | 422 |
| 227 | This action is only allowed for a forwarding queue | 409 |
| 228 | User is not authorized as sender for queue | 401 |
| 229 | User is not authorized as receiver for queue | 401 |
| 300 message errors | ||
| 301 | Message could not be found | 404 |
| 302 | Message ID is mandatory | 409 |
| 304 | Message body is mandatory | 422 |
| 305 | Message ID must be empty the ID is assigned by the receiving queue. | 409 |
| 306 | Message could not be sent because queue has exceeded maximum number of messages | 409 |
| 307 | Message could not be found in the requested transactional session context | 409 |
| 308 | Message could not be sent, because one or more destination queues have exceeded maximum number of messages | 409 |
| 309 | Message can not be deleted, because visibility timeout has expired | 409 |
| 310 | Unable to convert body encoding type | 409 |
| 311 | Body encoding could not be found | 404 |
| 312 | Body type could not be found | 404 |
| 313 | Queue is empty | 409 |
| 314 | CDATA is not allowed for SOAP | 409 |
| 400 user, permission & account errors | ||
| 401 | Must be SuperAdmin for this action | 401 |
| 402 | Account package does not allow more queue managers | 409 |
| 403 | Account package does not allow more queues | 409 |
| 404 | Account package does not allow more users | 409 |
| 405 | Account package does not allow more messages to be send today | 409 |
| 406 | Account package does not allow a message of this size to be send | 422 |
| 407 | Must be Admin for this action | 401 |
| 408 | User is not authorized as viewer for user | 401 |
| 409 | User is not authorized as moderator for user | 401 |
| 410 | User login can not be blank | 422 |
| 411 | User login is already taken | 422 |
| 412 | Unknown user | 404 |
| 413 | Cannot update user type | 409 |
| 414 | User email cannot be blank | 422 |
| 415 | User email is not a valid email address | 422 |
| 416 | User password can not be blank | 422 |
| 417 | User password must be at least 4 characters | 422 |
| 418 | User password confirmation cannot be blank | 422 |
| 419 | User password confirmation does not match password | 422 |
| 420 | User is not authorized as viewer for permission | 401 |
| 421 | User is not authorized as moderator for permission | 401 |
| 422 | Unknown permission | 404 |
| 423 | Permission queue manager cannot be blank | 422 |
| 424 | Permission queue wildmat cannot be blank | 422 |
| 425 | Permission user cannot be blank | 422 |
| 426 | Cannot alter account for resource | 422 |
| 900 technical errors | ||
| 901 | Unknown error. Please contact your supplier | 500 |
| 903 | There was a technical error while performing the operation with the message. Please contact your supplier | 500 |
| 902 | There was a technical error while performing the operation with the queue. Please contact your supplier | 500 |
Backward and Forward compatibility
General
OnlineMQ will provide backward compatibility for all its web services. When a new interface version is created the version number ("major-dot-minor" notation) is incremented and the old version will continue to function.
For interface changes which are not forward compatible, the major version number is incremented. For interface changes which are forward compatible, the minor version number is incremented.
Additions of optional fields and fields with defaults are considered compatible with the existing interface version and will lead to the increment of the minor version number. So the forward compatibility needs to be ensured by the client application (with the exception for SOAP clients).
For instance, if we add an optional <description> field to a resource, the minor version will be incremented. The older clients (working with the version which didn’t include the description field yet) simply never use the field in the request (which is allowed since it is optional) and they will ignore the field in the response (which is OK as well).
Currently only version 1.0 of the canonical is implemented. See Canonical for more information on the canonical schemas.
Note on the Canonical Schema validations: OnlineMQ does not provide extensible XSD schemas. And since the client should be forward compatible, the client cannot use strict Canonical Schema validations on the responses from OnlineMQ web services (the response could contain a field which was not in the previous XSD/RNG). The Canonical XSD can only be used for documentation purposes!
POX
The URL endpoint is different for major versions. All minor interface versions will have the same URL endpoint as the major version:
v1.0, v1.1, v1.x: /webservice_pox_v1
v2.0, v2.1, v2.y: /webservice_pox_v2 (not in existence yet...)
The interface version is set in the mandatory /onlinemq/header/version field in the canonical and handled dynamically. The response will always be in the same major message version as the request. But the minor version is always set to the latest minor version of the implementation. This means we require the POX clients to be forward compatible (they should ignore unknown fields in the response)
Example:
If you send a 1.0 request, you will get a 1.x response (x being the latest minor version implementation for major version 1).
If you send a 2.0 request, you will get a 2.y response (y being the latest minor version implementation for major version 2). (not in existence yet...)
SOAP
For SOAP we use the same setup as with POX, but we do not require the SOAP clients to be forward compatible (because the variety of SOAP libraries do not all fully support this). This means if you send a 1.0 request, you will always get a 1.0 response (even if 1.1 is the latest minor version).
The WSDL version on the other hand will always reflext the latest minor version (1.x). This means that older clients will keep working when a minor version is incremented, but the code generation tools for these clients can not by used with the live WSDL anymore. So if you are planning to rebuild your client often, please make a local copy of the WSDL. For instance for version 1.x & 2.y, the following paths should be used to get the WSDL:
v1.0, v1.1, v1.x: /webservice_soap_v1/wsdl
v2.0, v2.1, v2.y: /webservice_soap_v2/wsdl (not in existence yet...)
REST
note: there is a proposal to change this to embedding the interface version in the MIME type (Accept and Content-Type headers).
REST uses the POX conventions for the minor and major interface versions, so REST clients should also be forward compatible. The URL of the resources will however not change over the life cycle of the resource. This means that all different major versions will use the same URL.
The interface version for the RESTful interface is set in the HTTP headers using the "X-Rest-Interface-Version" header. This header is not mandatory for requests, but if not specified it will use the most recent RESTful interface version. Clients must therefore always set this HTTP header to avoid breaking the interface on a new major interface version.
Example:
GET /queue_managers HTTP/1.1 Content-Type: application/xml Accept: application/xml Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== X-Rest-Interface-Version: 1.0