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:

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

HTTP Responses

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

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!