OpenRosaRequest

Open Rosa Request

Much of OpenRosa communication comes in the form of HTTP requests and responses. In order to properly maintain appropriate formatting and compatibility over time, it is ideal for some information to be consistently provided on both sides of these interactions.

HTTP Requests

All HTTP requests (GET/POST/etc) should contain certain information to ensure that the server is appropriately able to understand a client's requests and respond appropriately. Since not all requests contain a flexible data payload, all of this information should be provided in the form of headers.

The table of headers to be included for requests in OpenRosa 1.0 standards is as follows:

Header	Values	Required
Accept-Language	LocaleFormat	No. Response acceptable in any locale
X-OpenRosa-Version	1.0 (currently, obviously different in the future)	Yes
Date	The date on the device in Mon, 14 Feb 2011 16:48:15 GMT format	Yes

The table of url arguments that should be accepted for requests is as follows

Arg	Values	Required
items	true or false - Specifies whether to include the item count in the response envelope	No. Defaults to false

HTTP Responses

The list of expected headers to be included in an OpenRosa response (regardless of the body of the response) is

Header	Values	Required
Content-Language	LocaleFormat	No, but recommended for i18n response purposes
X-OpenRosa-Version	1.0 (currently, obviously different in the future)	Yes
Date	The date on the server in Mon, 14 Feb 2011 16:48:15 GMT format	Yes

When a response is issued from an OpenRosa server, the format of the response payload will often be defined by the specific API (Form List, for instance). However, APIs which are fundamentally transactional (user registration, form submission, etc) all contain similar semantics. As such, they will utilize a shared XML Envelope of the format

     <OpenRosaResponse xmlns="http://openrosa.org/http/response" items=""> <!-- items: Optional number of how many payloads are included in this envelope -->
         <message nature=""/>                                              <!-- 0 or 1: message payload to be displayed to the user. Nature is an optional tag to group messages by type -->
         <*/>                                                              <!-- 0 or many: additional payloads to be parsed per platform-->
     </OpenRosaResponse>

For Example:

    <OpenRosaResponse xmlns="http://openrosa.org/http/response" items="3">
        <message nature="submit_success">Some message to be displayed to the user</message>
        <Registration xmlns="http://example.org/user/registration"/> <!-- optional -->
        <!--... Some platform specific response ...-->
    </OpenRosaResponse>

API's using this response can then include their namespaced payload inside of the response. This response should be handled in a unified way on the client, regardless of the specific submission. IE: Any time an OpenRosa response envelope is received, any of its payloads should be parsed properly.

Any responses included in the envelope that are unrecognized by the client should be ignored without error.

Since the server cannot receive confirmation that a response was successfully retrieved, any responses included in the envelope should be considered idempotent.

The message component of a response envelope should be returned (if possible) in the language specified by the Accept-Language header ID. The nature attribute of a message is an optional ID which can be used to categorize the type of a response. If the nature of two messages is identical in a bulk operation, for instance, the assumption is that only one of them need be presented to a user (presumably the newest).

As an example, if a server submits 4 xforms, and receives the responses

    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message nature="submit_success">Thanks, you've submitted 4 forms today </message>
...
    </OpenRosaResponse>
...
    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message nature="submit_success">Thanks, you've submitted 5 forms today </message>
...
    </OpenRosaResponse>
...
    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message nature="submit_user_registered">User 'paul' created succesfully!</message>
...
    </OpenRosaResponse>
...
    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message nature="submit_success">Thanks, you've submitted 6 forms today</message>
...
    </OpenRosaResponse>

A client could present a message like:

Bulk Submit Complete

• Thanks, you've submitted 6 forms today
• User 'paul' created successfully!

CommCare recognizes the following OpenRosaRequest versions, provided as an `X-OpenRosa-Version` header in HTTP requests

X-OpenRosa-Version	Description	Default as Of
---------	------	---------
1.0	Base sync semantics	2.0
2.0	Signals that the device can process Asynchronous Sync responses	2.29
2.1	Minor release to signal CommCare 2.38 or above	2.38
3.0	Signals that CommCare will accept a 422 form submission response to quarantine the submission	2.40