This document describes the Magpi inbound API, which allows Magpi client applications and other software to push data to the Magpi server at www.magpi.com . To pull data from Magpi's servers, you will need to use the Magpi Outbound API.


To use this API, you must have an account at www.magpi.com 

 

1.       Background

 

This document describes the API for transactions between the Magpi server (http://www.magpi.com) and client software. Client software can run on mobile devices (such as J2ME/iPhone/Android applications), or, software running on another server (such as a forms storage server, a document processing server).   In a transaction, the client sends a request to the server, waits for a response from the server, processes the response, and gives the necessary response to the user.

Before describing the interaction between the client and the server, it is important to note that the client-server transactions use a set of unique codes.  Depending on the success or failure of a transaction, certain codes that are returned by the server to signify the status of the request.   

Server requests do not always return codes. For example a request for a form will lead to either the form being returned if the request was successful or a code being returned if the request failed for some reason. The return code should signify to the client, the source, or the reason for the failure.

 

2.       Return Codes

Below are the return codes for different exceptions types occurring in the server. It is the responsibility of the client to check the return from a transaction for the possibility of being a code.

 

Code

Description

400

MOBILE_RESPONSE_ERROR_IN_DOWNLOAD. Signifies that there was an error in server downloading a form or any other item that was being downloaded.

401

MOBILE_RESPONSE_SURVEYNOTEXIST. This code is given when the client request for a survey or a form that is not existent on the server. This code may also be returned if the user attempts to perform an action on a survey that is non existent. Such activity may involve an activity like data upload for a non-existent survey.

402

MOBILE_RESPONSE_NODOWNLOAD_PERMISSION. This code is returned if the user the client is running as is not permitted to download a form for which he/she is making a request. Details on the access rules imposed on forms on the server are available in the Magpi user guide.

 

 

600

MOBILE_RESPONSE_SUCCESS_CODE. This is the most welcome code that signifies the success of any action or request to the server for which do data response is expected from the server. This code is returned for successful login, successful form data upload and many more other successful operations.

601

MOBILE_RESPONSE_TYPE_INVALIDUSER. This code is returned in any operation that involves the authentication of a user to signify that the username and password provided are not valid.

602

MOBILE_RESPONSE_TYPE_DBERROR. This code is retuned if there was a database related error in performing the requested operation.

603

MOBILE_RESPONSE_TYPE_SURVEYNOTEXIST. This code is given if a request is made for a non existent survey or form.

604

MOBILE_RESPONSE_TYPE_USER_NEW. This type of response is given if the user information passed to server about the current user signifies that the user is not registered with the server. This means that the username(email) specified for the username does not exists on the database. This might a sign of wrong entry of username(email) by the user.

605

MOBILE_RESPONSE_TYPE_NO_DOWNLOAD_PERMISSION. Signifies that the user has no permission to download the selected form or survey.

606

MOBILE_RESPONSE_TYPE_INVALID_FIELDS.  This code is returned to signify that the field structure for the fields sent on a request to the server is incorrect. An example is when for example you are making a login request and you pass a username field parameter with a non standard parameter. Standard here refers to the standards laid out by the Magpi web server and the Magpi client.

 

 

700

MOBILE_RESPONSE_TYPE_USER_VALID. This is the response that is given if a username specified is valid.

701

MOBILE_RESPONSE_TYPE_INVALIDUSER_FOR_FORMLIST.  This code is returned if a wrong username or password is provided in the request for list of available forms for download.

702

MOBILE_RESPONSE_TYPE_DBERROR_FOR_FORMLIST.  This code is retuned if a database error or exception occurs during the processing of the request for the list of formsa available for download.

703

MOBILE_RESPONSE_TYPE_SURVEYNOTEXIST_FOR_FORMLIST. This value is returned if there are no forms that exists on the server for the specific type of forms and the user. For example, this code is returned when a user requests for the list of public forms while none exists for that user

Most of the codes above have the capitalized, underscored name clearly describing their applicability and depends on the context. For example a return code of 600 would imply a successful login for a login request while the same return code would imply a successful data upload for a survey data upload request.

 

3.       Server Calls 

This section describes the server calls and corresponding parameters passed in each call. There is also entry for the request method used. The only possible methods are GET and POST. This refers to the http form request methods. This is usually the attribute that is provided in an html form declaration. For example

method='POST' action="/login">. The actions are identified in terms of different transactions that might take place between the client and the server.

In this specification there are some variables used which are listed below.

  • $server_root=http://www.magpi.com

 

In the document,  parameters are reused. An example of a reuse is $server_root/login which will translate to https://www.magpi.com/login/auth

 

Transaction

Description

Login Request

URL: $server_root/AuthenticateLogin

Request Method: GET or POST

Parameters:

Name

Value

requestType

login

id

The username of the user (email address used for registering with the server)

pwd

The password as specified during the same registration

 

Response: One of the codes specified above

 

 

Forms List Request

URL: $server_root/GetFormList

Request Method: GET or POST

Parameters:

Name

Value

requestType

formlist

userid

The username of the user (email address used for registering with the server)

pwd

The password as specified during the same registration

formtype

The type of form. Can be one of the following constants (private,public)

Formtag(not mandatory)

The tag that has been specified for the form during form creation

Formname(not mandatory)

The name filter for the forms to be returned

 

Response: The response is an xml like notation with the following format

    

Survey name2

    

Survey name2

    

Survey n -1

    

Survey n

 

 

 

Get Survey Form

URL: $server_root/GetSurveyForm

Request Method: GET or POST

Parameters:

Name

Value

requestType

getSurveyForm

id

The username of the user (email address used for registering with the server)

pwd

The password for the user requesting the forms.

name

The name of the form to be downloaded which is one of the names provided in the forms list request described above

 

Response: An xfrom representation of the form requested. The structure of xforms is d escribed in details on javarosa.org

Upload Records to the server

URL: $server_root/UploadRecordsNew

 

Description: used to add a new record or update an already existing record.  In the case that the record already exists on the server and the client is making an update, the client makes a call the same way as it would call for a brand new record, except, server will discover that it is an update by realizing that the record of the same timestamp already exists in the server and accordingly updates the record.

 

Request Method: POST

Parameters:

This is a unique case that has been modeled to deal with the restricted resources available in the mobile device. For this, you can only be able to upload one record at a time. The method does not use the http parameters as usual but instead the server acquires the connections input stream and processes the whole request stream data. Here the nature and order of the data being sent is specified as follows.

The client uses the DataOutputStream to write the records to the server. As such there might be some differences in the way the record is sent due to the stream metadata info included in the stream. Her'es a sample code for sending the a record to the server.

        out.writeUTF(userId);

        out.writeUTF(password);

        out.writeUTF(surveyName);

        out.writeLong(dateModified);

        out.writeLong(recordId.getMostSignificantBits());

        out.writeLong(recordId.getLeastSignificantBits());

        out.writeUTF(dataTree);

out here is an object of type DataOutputStream

The parameters are written out exactly in the order specified. Any other format is not accepted. These restrictions were put in place due to the large overhead that was being experienced in storing large xml trees in the limited phones memory especially for surveys with many questions.

First you write out the user id which is the email address of the user submitting the record.

Next you write out the password for the user

Next you write out the name of the survey for which you are submitting the record.

Next you write put the date modified for the record being submitted.

Next you write out a long value that is a long value with the record id.

Next you write the data tree which is a well formed xml structure with the following sample format for a sample survey

  

         Moscow's the mine' city ma'am

         me!!

         ~

         Banana|Mango|Orange a-multi-choice-question>

         Yes a-single-choice-question>

  

 

Label questions: create an element that has the identifier for the label as usual but set the value of the element with a tilde (~). This is also the format used for questions that require answers but which the user supplied no answers for.

Multiple choice questions: separate the answers provided with a pipe (|).

 

Response: One of the codes specified above. 600 if successful upload, and other codes otherwise

Request Method: GET or POST

Parameters:

Name

Value

requestType

login

Id

The username of the user (email address used for registering with the server)

Pwd

The password as specified during the same registration

 

 

4.       References

 

Please use this specification as is and give forward any questions or clarifications you might be having to support@magpi.com (or click the New button, above, to open a new support ticket) where you will be guaranteed to receive a response within 24 hours. Please ask any questions and we will be there for clarification or rectification.