Open Rosa User Registration API

This document provides a specification for the API for which OpenRosa compliant servers receive and respond to user registrations. This document is currently a proposal in its second round.

Overview

OpenRosa compliant servers often need to accept user registrations from remote sources such as phones or other servers. In order to simplify and consolidate the amount of new code to be

Implementation

User registrations are received by the servers as HTTP POSTs to a REST url with an xml payload containing the registration information. The response to a registration request is an xml payload containing

Authentication

'''Note: The authentication section refers to the as-of-yet still proposed Authentication standard for OpenRosa servers, and is subject to change along with that proposed standard'''

Requests to the server should either be served without authentication, or using the HTTPS Secure OpenRosa Authentication standard. No request should be served with authentication in other formats, including having authentication credentials included in the GET/POST URL. (However, you can send unsecured identifiers required to generate reports - just recognize that they are, in fact, unsecured.)

Response Codes

If the registration is received and contains valid data, the response of the server is should be the xml payload for server response, along with the 200 HTTP OK response code.

If the request was in an invalid format, the format of the response is undefined, and the appropriate response code from the following list should be provided. If the request was well-formed, but the information inside of the request cannot be used as intended, the appropriate response code should be used, and the appropriate xml payload should be returned.

• '''400 BAD REQUEST''' - The user registration couldn't be completed and cannot ever be completed with identical paramters. The message in the response should clarify what parameters were invalid (like a username which is already taken).
• '''401 UNAUTHORIZED''' - When a request fails authentication.

Registration Payload Format

<Registration xmlns="http://openrosa.org/user/registration"/>

    <username/>                       <-- Exactly One
    <password/> (SHA-1 Hash)          <-- Exactly One
    <uuid/> (unique ID)               <-- Exactly One
    <date/>                           <-- Exactly One

    <registering_phone_id/>           <-- At Most One
    <token/>                          <-- At Most One

    <user_data>                       <-- At Most One
        <data key=""></data>          <-- Arbitrarily Many
    </user_data>
</Registration>

Registration Server Response Payload Format

The response will consist of a OpenRosa Request Response envelope, which is likely to contain additional information about the user. This information will come inside of another registration transaction which may be included in the response. If so, it should be parsed and any user objects should be ammended with the relevant data.

If the user object returned modifies the user object registered in any way, this information should be reflected in the message (see example below).

Users should not be considered to be "created" on the client until a 200 response is received from the server and the resulting response has been processed (including any Registration payloads in full).

    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message>User has been registered</message>
        <Registration xmlns="http://openrosa.org/user/registration"/> <!-- optional -->
    </OpenRosaResponse>

Reference Implementation

A completed registration packet

<Registration xmlns="http://openrosa.org/user/registration">

    <username>ctsims</username>
    <password>sha1$59fa0$5ee434d9417008f029542ed70bba95a08873c7fd</password>
    <uuid>3F2504E04F8911D39A0C0305E82C3301</uuid>
    <date>2009-08-12</date>

    <registering_phone_id>3F2504E04F8911D39A0C0305E82C3301</registering_phone_id>

    <user_data>
        <data key="chw_id">13/43/DFA</data>
    </user_data>
</Registration>

A clean response

    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message>User 'ctsims' has been registered</message>
    </OpenRosaResponse>

A response which adds data which the server is aware of about the user.

    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message>User has been registered</message>
        <Registration xmlns="http://openrosa.org/user/registration">
            <username>ctsims</username>
            <password>sha1$59fa0$5ee434d9417008f029542ed70bba95a08873c7fd</password>
            <uuid>3F2504E04F8911D39A0C0305E82C3301</uuid>
            <date>2009-08-12</date>
            <user_data>
                <data key="region">New England</data>
                <data key="domain">collection</data>
            </user_data>
        <Registration >
    </OpenRosaResponse>

A response which modifies the user's registered name automatically due to a conflict

    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message>Username 'ctsims' is unavailable. User registered as 'ctsims2'</message>
        <Registration xmlns="http://openrosa.org/user/registration">
            <username>ctsims2</username>
            <password>sha1$59fa0$5ee434d9417008f029542ed70bba95a08873c7fd</password>
            <uuid>3F2504E04F8911D39A0C0305E82C3301</uuid>
            <date>2009-08-12</date>
        <Registration >
    </OpenRosaResponse>

A 400 response message

    <OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message>Username 'ctsims' is unavailable.</message>
    </OpenRosaResponse>