This document describes the Magpi inbound API, which allows Magpi client applications and other software to push data to the Magpi server at https://app.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 (https://app.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=https://app.magpi.com

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

Transaction

Description

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 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. Sample Code to create new record and update existing record

import java.io.*;
import java.net.HttpURLConnection;
import java.net.Socket;
import java.net.URL;
import java.net.UnknownHostException;

public class InboundTest {
    private static final String USER_ID = "username"; //your username
    private static final String PASSWORD = "password"; //your password
    private static final String VERSION = "5.0";
    private static final String MAGPI_SERVER_URL = "https://app.magpi.com";
    private static final String ADD_UPDATE_ENDPOINT = "/UploadRecordsNew";

    public static void main(String args[]) {
        String result = executePost();
        System.out.println("Result..........." + result);
    }

    public static String executePost() {
        HttpURLConnection connection = null;

        try {
            //Create connection
            URL url = new URL(MAGPI_SERVER_URL + ADD_UPDATE_ENDPOINT);
            connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
            connection.setRequestProperty("charset", "utf-8");
            connection.setRequestProperty("Content-Language", "en-US");
            connection.setInstanceFollowRedirects(false);
            connection.setUseCaches(false);
            connection.setDoOutput(true);
            //Send request
            connection.connect();
            DataOutputStream wr = new DataOutputStream(connection.getOutputStream());
            wr.writeUTF(USER_ID);//userId/username
            wr.writeUTF(PASSWORD); //password
            wr.writeUTF("3492141126519062187"); //surveyId i.e. form external id
            wr.writeUTF("2020-10-29 11:37:10"); //dateSaved date, format: yyyy-MM-dd HH:mm:ss
            wr.writeUTF("1613950553999"); //recordId
            //xml dataTree
            wr.writeUTF("<?xml version='1.0' encoding='UTF-8' ?>" +
                    "<data>" +
                    "<Age>21</Age>" + //wrap data/answer in question (data field) name
                    "<Name>Magpi Support</Name>" +
                    "</data>");
            wr.writeDouble(24.780769); //latitude
            wr.writeDouble(95.305140); //longitude
            wr.writeUTF(VERSION); //version
            wr.writeUTF("4e9216y60b6d44085a37c2b4d5d1ce5b6"); //uuid, if this uuid is found in system then it's a record update else its a new record

            //Get Response
            InputStream is = connection.getInputStream();
            BufferedReader rd = new BufferedReader(new InputStreamReader(is));
            StringBuilder response = new StringBuilder(); // or StringBuffer if Java version 5+
            String line;
            while ((line = rd.readLine()) != null) {
                response.append(line);
                response.append('\r');
            }
            rd.close();
            return response.toString();
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }

}

Keep NoteThe sample code has been used with a form that has two question i.e Integer question Age and Plain text question Name.
The question names variables(Age and Name) in the code are the Data field name in the form.
If you are working with more than two questions, add the rest of the questions inside the data tag <data>.

Magpi Test Form

5. References

Please use this specification as is and give forward any questions or clarifications you might be having to [email protected] (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.

Magpi Inbound API Print

1. Background

2. Return Codes

3. Server Calls

4. Sample Code to create new record and update existing record

5. References

Related Articles