This document is published by Appiyo Technologies Pte., Ltd., without any warranty.

Transcription

1 MeOnCloud REST APIs

2 2015 All rights reserved. All trademarks acknowledged This document is published by Appiyo Technologies Pte., Ltd., without any warranty. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose without the written permission of Appiyo Technologies Pte., Ltd. Improvements and changes to this text necessitated by typographical errors, inaccuracies of current information or improvements to software programs and/or equipment, may be made by at any time and without notice. Such changes will, however, be incorporated into new editions of this document. Any hard copies of this document are to be regarded as temporary reference copies only.

3 Table of Contents 1 Getting Started with the MeOnCloud.com REST APIs... 5 URI Structure of Resources Quick Start REST API References Java Example Requests... 28

4 List of Tables Table 1 - Types of HTTP Methods... 6 Table 2 - Input Parameter description for Log in Table 3 - Response explanation for Log in Table 4 - List of MeOnCloud resources supported by REST APIs Table 5 - Input Parameter description of Send Message Table 6 - Response explanation of Send Message Table 7 - Input Parameter description of Create a Group Table 8 - Response explanation of Create a Group Table 9 - Input Parameter description of Edit Group Table 10 - Input Parameter description of Filter Group Result Table 11 - Response explanation of Filter Group Result Table 12 - Response explanation of Get Group Details Table 13 - Response explanation of Add Customer to Group Table 14 - Input Parameter description of Filter Customers by Name Table 15 - Response explanation of Filter Customers by Name Table 16 - Input Parameter description of Filter Customers by Group Table 17 - Response explanation of Filter Customers by Group... 25

5 1 Getting Started with the MeOnCloud.com REST APIs Introduction to MeOnCloud.com REST APIs In order to interact with you may consume the powerful and simple REST APIs that MeOnCloud provides. Each MeOnCloud REST resource has a specific URI name as its identification. MeOnCloud REST APIs access these resources via their URI by using standard HTTP methods (POST, PUT, GET and DELETE). The response format is JSON. It is easy to integrate and use. You can use any development environment/language to access the REST APIs as they are based on open standards. About this document This document guides you to use MeOnCloud REST APIs. The prerequisites to use this document include, basic familiarity with software development and web services. This document helps you understand:- authentication flow HTTP request including URI structure JSON responses (Both Success and Failure responses) description of the request and response parameters. 5 P a g e

6 Understanding MeOnCloud.com REST Resources Table 1 displays the types of HTTP methods that provides access to the REST resources. Method GET POST PUT DELETE Description Retrieves and displays information about requested resource Creates new resources Updates specific resource for a given id Deletes resources for given id Table 1 - Types of HTTP Methods URI Structure of Resources General URI form of all the resources: resource Example: Name of the requested resource Based on the request, the general URI may have one or more combinations of the following information appended at the end. Some example URIs are: id> resource id Unique id assigned for the resource Example: name Name of the resource to find startdate Filters the resource created on/from the specified date enddate Filters the resource created before the specified date perpage Sets the page limit for displaying the list of filtered resource from Specifies from which page the resource result has to be filtered Example: id>/<action name> action name Action to be applied to the specified resource Example: 6 P a g e

7 2 Quick Start The examples in this guide use Java and curl to send HTTP requests to access the REST resources. Understanding the Authentication Flow MeOnCloud uses authentication token (generated during login with user s id and password) as the authentication to protect their data from unauthorized access. Before sending REST request for accessing MeOnCloud resources, you must get the authentication token. Use your login credentials for requesting authentication token via POST method. MeOnCloud verifies the given credentials and gives the generated authentication token in the JSON format. This authentication token should be added to the http cookie header in all subsequent requests for accessing MeOnCloud resources. During each login, a new authentication token is generated. Following diagram explains the authentication flow in MeOnCloud: 7 P a g e

8 Step One: Getting Authentication Token You can use the Login REST API to login to your MeOnCloud account using your authentication credentials (user id and password). An authentication token (in JSON format) is created which is required for further access of the resources. The request format for login is:- Request URL: Request Method: POST Response Content Type: "application/json" Example curl Request for getting authentication token curl -d " = " -d "password=password" -c <cookie> Example Java Code for getting authentication token Let s see how to get the authentication token using the user name and password. //Request for getting the authentication token URL loginurl = new URL(" HashMap<String, String> params = new HashMap<String,String>(); params.put(" "," "); params.put("password","password"); StringBuilder url = new StringBuilder(); if(params!= null && params.size() > 0) for(map.entry<string, String> entry : params.entryset()) url.append(entry.getkey()); url.append("="); url.append(urlencoder.encode(entry.getvalue())); url.append("&"); String data = url.tostring(); HttpURLConnection authconnection = (HttpURLConnection) loginurl.openconnection(); authconnection.setdooutput(true); authconnection.setrequestmethod("post"); authconnection.setrequestproperty("accept", "application/json"); DataOutputStream wr = new DataOutputStream( authconnection.getoutputstream ()); wr.writebytes(data); //getting cookie from header fields and storing in the string cookie //to pass in the subsequent requests InputStream stream = authconnection.getinputstream(); BufferedReader br = new BufferedReader(new InputStreamReader(stream)); 8 P a g e

9 String response = br.readline(); JSONParser parser = new JSONParser(); JSONObject responsejson = null; try responsejson = (JSONObject) parser.parse(response); catch(parseexception e) System.out.println("error while parsing response : " + e.getmessage()); boolean status = (boolean) responsejson.get("status"); String cookie = ""; if(status) JSONObject tokenresponse = (JSONObject) responsejson.get("response"); cookie = (String) tokenresponse.get("token"); System.out.println("Cookie = " + cookie); wr.flush(); wr.close(); authconnection.disconnect(); The code given below stores the authentication token inside the String cookie that has been received from the login response. JSONObject tokenresponse = (JSONObject) responsejson.get("response"); String cookie = (String) tokenresponse.get("token"); The response to the login request is given below: Success Response "message": "message": "Login success", "code": 0, "response": "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": true 9 P a g e

10 Failure Response for incorrect user credentials "message": "message": "Login failed", "code": 1403, "response":, "status": false Input Parameters password id used to login to MeOnCloud Password used to login to MeOnCloud Table 2 - Input Parameter description for Log in Response Explanation message code token status Success or Failure message for the request Response code for the request Example - 0 = Login Success 1403 = Login failed Generated authentication token True = Request has been processed successfully False = Request has not been processed Table 3 - Response explanation for Log in Step Two: Adding Authentication Token in Subsequent Requests Let s see how to send POST request by adding the authentication token that we received from the login response. To send HTTP request using following code, replace <Request URL>, <Input Parameter> and <Parameter Value> with appropriate data. Request Method: POST //Sending POST request URL requesturl = new URL("<Request URL>"); HashMap<String, String> param = new HashMap<String,String>(); param.put("<input Parameter>","<Parameter Value>"); StringBuilder url = new StringBuilder(); if(params!= null && params.size() > 0) for(map.entry<string, String> entry : params.entryset()) url.append(entry.getkey()); url.append("="); 10 P a g e

11 url.append(urlencoder.encode(entry.getvalue())); url.append("&"); String data = url.tostring(); HttpURLConnection connection = (HttpURLConnection)requestUrl.openConnection(); connection.setdooutput(true); //adding cookie string from POST response of login connection.addrequestproperty("cookie", "authentication-token=" + cookie); connection.setrequestmethod("post"); DataOutputStream wrt = new DataOutputStream( connection.getoutputstream()); wrt.writebytes(datas); //BufferedReader has the response data BufferedReader in = new BufferedReader( new InputStreamReader(connection.getInputStream())); String inputline; while ((inputline = in.readline())!= null) System.out.println(inputLine); in.close(); connection.disconnect(); The authentication token stored inside the String cookie is added to the cookie header. connection.addrequestproperty("cookie", "authentication-token=" + cookie); To know about sending requests via other HTTP methods, refer to: Java Example Requests Step Three: Reading Response By sending an HTTP request you can get a response in JSON format. The response content will vary depending on the HTTP method and request parameters used. 11 P a g e

12 3 REST API References Following section includes example REST requests written using Java and curl. The response is in JSON format. All the resource URI follows the base URI Table 4 includes the list of MeOnCloud resources supported by REST APIs with their brief description. Click a resource name to get more information about the resource. URI HTTP Method Description /e/enterprise/sendmessage POST Sends message to customers/groups /e/enterprise/group POST Creates a new group /e/enterprise/groups/<groupid> /e/enterprise/groups?name=&startdate=&e nddate=&from=0&perpage=32 /e/enterprise/groups/<groupid>/customer? name=&from=0&perpage=30&mapped= /e/enterprise/groups/<groupid>/add_custo mers /e/enterprise/groups/<groupid>/remove_cu stomers /e/enterprise/customers?name=&isactive=t rue&startdate=&enddate=&from=0&perpa ge=30 PUT GET DELETE GET GET PUT PUT GET Modifies group details Displays the details of the group for given id Deletes the group of given id Filters the group result based on the search Filters customer result by the group they are mapped to get the details of searched customers Adds customers to the group of the given id Removes the customers from the group of the given id Filters customer result by their name to get the details of searched customers /account/logout GET Signs out from MeOnCloud Table 4 - List of MeOnCloud resources supported by REST APIs 12 P a g e

13 Send Message Using the request URL given below, send messages to customers/groups via POST method. The request format for sending a message is:- Request URL: Request Method: POST Response Content Type: "application/json" Input Parameters contenttype short full sendtype recipients MD (Mark Down) = Includes formatting and hyperlink attachment options TEXT = Do not include formatting and hyperlink attachment options Message subject Message body sendtype decides the recipient type. 0 = Sends message to all customers 1 = Sends message to group 2 = Sends message to list of customers Recipient list depends on sendtype. If sendtype is 0 = Null (sends message to all) 1 = List of Group ids (sends message to groups of given ids) 2 = List of Customer ids (sends message to customers of given ids) Table 5 - Input Parameter description of Send Message Response Explanation status code message True = Request has been processed successfully False = Request has not been processed Response code for the request Example - 0 = Message sent 1403 = Customer/Group does not exist Success or Failure message for the request Table 6 - Response explanation of Send Message 13 P a g e

14 Example curl Request for sending message curl -b <cookie> -d "short=hi" -d "full=hi" -d "contenttype=md" -d "sendtype=2" -d "recipients=[107]" JSON Success Response "status": true, "message": "code": 0, "message": "Message send successfully", "response": JSON Failure Response for invalid group id "status": false, "message": "code": 1403, "message": "Inactive enterprise", "response": JSON Failure Response for invalid customer id "status": false, "message": "code": 1403, "message": "No customers available to send message", "response": 14 P a g e

15 Create a Group Send a request to the groups resource using the request URL given below via POST method with the input parameters group name and group description. The request format for creating a group is:- Request URL: Request Method: POST Response Content Type: "application/json" Input Parameters name desc Name of the group Description of the group Table 7 - Input Parameter description of Create a Group Response Explanation status code message id True = Request has been processed successfully False = Request has not been processed Response code for the request Example - 0 = Group created 1403 = Group name already exist Success or Failure message for the request Unique id assigned to the group Example curl Request for create group Table 8 - Response explanation of Create a Group curl -b <cookie> -d "name=mygroup" - d "desc=mygroup Description" JSON Success Response "status": true, "message": "code": 0, "message": "Group created successfully", "response": "id": "54daef e3d84ae3280" 15 P a g e

16 JSON Failure Response for using already registered group name "status": false, "message": "code": 1403, "message": "The group name is already registered", "response": Edit Group You can modify your group details. Send a request to the groups resource using the request URL given below via PUT method with the required group id. The request format for edit group is:- Request URL: Request Method: PUT Response Content Type: "application/json" Input Parameters name desc Name of the group Description of the group Example curl Request for modifying group details Table 9 - Input Parameter description of Edit Group curl -b <cookie> -X PUT -d "name=mygroup" -d "desc=description about MyGroup" JSON Success Response "message": "code": 0, "message": "Group updated successfully", "status": true JSON Failure Response for invalid group id "status": false, "message": "code": 1403, "message": "No group exists with given id", "response": 16 P a g e

17 JSON Failure Response for using already registered group name "status": false, "message": "code": 1403, "message": "The group name is already registered", "response": Filter Group Result Filter the group result to get the details of the searched group. Send a request to the groups resource using the request URL given below via GET method with the required group name and other parameters. The request format for filtering group result is:- Request URL: name>&startdate=&enddate=&from=0&perpage=32 Request Method: GET Response Content Type: "application/json" Input Parameters name startdate enddate perpage from Group name that has to be searched from the available list Filters the groups created on/from the specified date Filters the groups created before the specified date Sets the page limit for displaying the list of filtered groups Specifies from which page the group result has to be filtered Table 10 - Input Parameter description of Filter Group Result Response Explanation id name desc more Unique id assigned to the group Name of the group of given id Description of the group True = More groups are available to show False = No more groups available Table 11 - Response explanation of Filter Group Result 17 P a g e

18 Example curl Request for filter group result curl -b <cookie> -G -d "name=mygroup" -d "startdate=" -d "enddate=" -d "perpage=32" -d "from=0" JSON Response "status": true, "message": "code": 0, "message": "List of groups", "response": "groups": [ "id": "54daef e3d84ae3280", "name": "MyGroup", "desc": "Description about MyGroup" ], "more": false Get Group Details Use the groups resource to get the details of a group. Each group has a unique id assigned which could be used for its access. Send a request to the groups resource using the request URL given below via GET method with the required group id. The request format for getting group details is:- Request URL: Request Method: GET Response Content Type: "application/json" Response Explanation id name desc Unique id assigned to the group Name of the group of given id Description of the group Example curl Request for getting group details Table 12 - Response explanation of Get Group Details curl -b <cookie> 18 P a g e

19 JSON Success Response "status": true, "message": "code": 0, "message": "Group details", "response": "id": "54daef e3d84ae3280", "name": "MyGroup", "desc": "Description about MyGroup" JSON Failure Response for invalid group id "status": false, "message": "code": 1403, "message": "No group exists with given id", "response": Add (Map) Customer to Group Add customers to your group. Send a request to the groups resource using the request URL given below via PUT method with the required group id and customer ids. The request format for add customer is:- Request URL: Request Method: PUT Response Content Type: "application/json" Response Explanation invalidcustomers List of specified customer ids that are invalid Table 13 - Response explanation of Add Customer to Group Example curl Request for adding customer to group curl -b <cookie> -X PUT --data-urlencode 'customers="ids":[107,102]' mers 19 P a g e

20 JSON Success Response "status": true, "message": "code": 0, "message": "Customer(s) mapped to the group successfully", "response": "invalidcustomers": [ ] JSON Failure Response for invalid group id "status": false, "message": "code": 1403, "message": "No group exists with given id", "response": JSON Failure Response for invalid customer id "status": false, "message": "code": 1403, "message": "No customer(s) available for mapping", "response": Remove Customer from Group You can remove existing customers from group. Send a request to the groups resource using the request URL given below via PUT method with the required group id and customer ids. The request format for remove customer is:- Request URL: Request Method: PUT Response Content Type: "application/json" Example curl Request for removing customer from group curl -b <cookie> -X PUT --data-urlencode 'customers="ids":[107,102]' stomers 20 P a g e

21 JSON Success Response "message": "code": 0, "message": "Customer(s) removed from the group successfully", "status": true JSON Failure Response for invalid group id "status": false, "message": "code": 1403, "message": "No group exists with given id", "response": JSON Failure Response for invalid customer id "status": false, "message": "code": 1403, "message": "No customers available for removing", "response": Delete Group Allows to delete your group. Send a request to the groups resource using the request URL given below via DELETE method with the required group id. The request format for delete group is:- Request URL: Request Method: DELETE Response Content Type: "application/json" Example curl Request for delete group curl -b <cookie> -X DELETE JSON Success Response "message": "code": 0, "message": "Group deleted successfully", "status": true 21 P a g e

22 JSON Failure Response for invalid group id "status": false, "message": "code": 1403, "message": "No group exists with given id", "response": 22 P a g e

23 Filter Customers by Name Filter the customers result by their name to get the details of the searched customer. Send a request to the customers using the request URL given below via GET method with the required customer name along with other parameters. The request format for filtering customers result is:- Request URL: name>&isactive=true&startdate=&enddate=&from=0&perpage=30 Request Method: GET Response Content Type: "application/json" Input Parameters name isactive startdate enddate perpage from Customer name that has to be searched from the available list True = Customer exist False = Customer does not exist Filters the customers subscribed on/from the specified date Filters the customers subscribed before the specified date Sets the page limit for displaying the list of filtered customers Specifies from which page the customer result has to be filtered Response Explanation Table 14 - Input Parameter description of Filter Customers by Name cid name phone more Unique id assigned to the customer Name of the customer of given id Phone number of the customer True = More customers are available to show False = No more customers available Table 15 - Response explanation of Filter Customers by Name Example curl Request for filtering customers by name curl -b <cookie> -G -d "name=vijay" -d "isactive=true" -d "startdate=" -d "enddate=" -d "perpage=30" -d "from=0" 23 P a g e

24 JSON Success Response "status": true, "message": "code": 0, "message": "List of customers", "response": "customers": [ "cid": 107, "phone": " ", "name": "vijay", "photo": "" ], "more": false JSON Failure Response for invalid customer name "status": false, "message": "code": 1403, "message": "Inactive enterprise", "response": JSON Failure Response for null mandatory input parameters "status": false, "message": "code": 1403, "message": "Start date is mandatory", "response": 24 P a g e

25 Filter Customers by Group Filter the customers result by the group they are mapped to get the details of the searched customer. Send a request to the groups resource using the request URL given below via GET method with the required customer name and group id along with other parameters. The request format for filtering customers result is:- Request URL: name>&from=0&perpage=30&mapped=true Request Method: GET Response Content Type: "application/json" Input Parameters name perpage from mapped Customer name that has to be searched from the available list Sets the page limit for displaying the list of filtered customers Specifies from which page the customer result has to be filtered True = Customer is mapped to the group False = Customer is not mapped to the group Response Explanation Table 16 - Input Parameter description of Filter Customers by Group cid name phone photo more Unique id assigned to the customer Name of the customer of given id Phone number of the customer Link of the customer s profile image True = More customers are available to show False = No more customers available Table 17 - Response explanation of Filter Customers by Group 25 P a g e

26 Example curl Request for filtering customers by group curl -b <cookie> -G -d "name=vijay" -d "perpage=30" -d "from=0" -d "mapped=true" JSON Success Response "status": true, "message": "code": 0, "message": "List of customers", "response": "customers": [ "cid": 107, "phone": " ", "name": "vijay", "photo": "" ], "more": false 26 P a g e

27 Logout Using the request URL given below, logout from MeOnCloud via GET method. The request format for logout is:- Request URL: Request Method: GET Response Content Type: "application/json" Example curl Request for logout curl -b <cookie> 27 P a g e

28 4 Java Example Requests To send HTTP request using following codes, replace <Request URL>, <Input Parameter> and <Parameter Value> with appropriate data. Request Method: PUT //Sending PUT Request URL requesturl = new URL("<Request URL>"); HashMap<String, String> param = new HashMap<String,String>(); param.put("<input Parameter>","<Parameter Value>"); StringBuilder url = new StringBuilder(); if(params!= null && params.size() > 0) for(map.entry<string, String> entry : params.entryset()) url.append(entry.getkey()); url.append("="); url.append(urlencoder.encode(entry.getvalue())); url.append("&"); String data = url.tostring(); HttpURLConnection connection = (HttpURLConnection)requestUrl.openConnection(); connection.setdooutput(true); //adding cookie string from POST response of login connection.addrequestproperty("cookie", "authentication-token=" + cookie); connection.setrequestmethod("put"); DataOutputStream wrt = new DataOutputStream( connection.getoutputstream()); wrt.writebytes(datas); //BufferedReader has the response data BufferedReader in = new BufferedReader( new InputStreamReader(connection.getInputStream())); String inputline; while ((inputline = in.readline())!= null) System.out.println(inputLine); in.close(); connection.disconnect(); 28 P a g e

29 Request Method: GET //Sending GET request URL requesturl = new URL ("<Request URL>"); HttpURLConnection connection = (HttpURLConnection)requestUrl.openConnection(); //adding cookie string from POST response of login connection.addrequestproperty("cookie", "authentication-token=" + cookie); connection.setrequestmethod("get"); //BufferedReader has the response data BufferedReader in = new BufferedReader( new InputStreamReader(connection.getInputStream())); String inputline; while ((inputline = in.readline())!= null) System.out.println(inputLine); in.close(); connection.disconnect(); 29 P a g e

30 Request Method: DELETE //Sending DELETE request URL requesturl = new URL( <Request URL>"); HttpURLConnection connection = (HttpURLConnection)requestUrl.openConnection(); //adding cookie string from POST response of login connection.addrequestproperty("cookie", "authentication-token=" + cookie); connection.setrequestmethod("delete"); //BufferedReader has the response data BufferedReader in = new BufferedReader( new InputStreamReader(connection.getInputStream())); String inputline; while ((inputline = in.readline())!= null) System.out.println(inputLine); in.close(); connection.disconnect(); Note: All the actions like getting details about resources, creating new resources, modifying existing resources or deleting resources can be performed only when you are logged- in.i.e. authentication token is required. 30 P a g e

31 Registered Office: Appiyo Technologies Pte., Ltd., 143, Cecil Street, 16-04, GB Building, Singapore Follow us on