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:

HeaderValuesRequired
Accept-LanguageThe key for what language a response is expected in.No. Response acceptable in any locale
X-OpenRosa-Version1.0 (currently, obviously different in the future)Yes
DateThe date on the device in Mon, 14 Feb 2011 16:48:15 GMT formatYes

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

ArgValuesRequired
itemstrue or false - Specifies whether to include the item count in the response envelopeNo. 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

HeaderValuesRequired
Content-LanguageThe key for the response locale.No, but recommended for i18n response purposes
X-OpenRosa-Version1.0 (currently, obviously different in the future)Yes
DateThe date on the server in Mon, 14 Feb 2011 16:48:15 GMT formatYes

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!

Updated

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.