Analytics-Plus Help

API Specification

 

Analytics Plus API uses HTTP as the underlying transport protocol. It is based on REST principles. The following are the basic points of how the REST APIs are structured:

 

  • Every table or report or dashboard in a Analytics Plus database can be uniquely identified using a URL.

  • The operation to be performed on the table/report/dashboard can be specified using the parameters in the URL.

  • The additional payload required to perform the operation should also be specified as parameters in the URL.

  • Every request has a response whose format can be controlled using parameters in the request URL.

 

It is important to understand the API specification clearly before referring to the actual API methods

 

  • Request Format

  • Response Format.

  • Error Handling.

  • Common Parameters.

 


 

Request Format

All API requests should be placed as HTTPS POST request. The request consists of the following components:

 

  • URI (Universal Resource Identifier. Also commonly known as URL)

  • Common Mandatory Parameters sent as Query String in the URL

  • Parameters sent via the body of the POST request

 

URI

The URI points to the resource inside Analytics Plus over which the action is to be performed.

 

Base URL:

https://<server_hostname>:<portnumber>/api

 

To access a table or report:

https://<server_hostname>:<portnumber>/api/<loginemailaddress>/<databasename>/<tablename or reportname>

 

URI componentDescription
 <server_hostname>This should be the hostname.
 <portnumber>

This should be the port number (8443 is default)

 <loginemailaddress>

This should be the Analytics Plus login Email Address of the owner of the database (e.g., abc@zoho.com)

 <databasename>

This should be the name of the database on which the API is to be executed. (e.g., EmployeeDB)

 <tablename or reportname>

The name of the view (table or report or query table or dashboard name) over which the action is to be executed. (e.g., EmployeeDetails)

 

PARAMETERS TO BE PASSED IN QUERY STRING

The following snippet shows the common parameters that should be passed as Query string with the URI defined above:

 

<URI>?ZOHO_ACTION=[IMPORT/EXPORT...]&ZOHO_OUTPUT_FORMAT=[XML/JSON/PDF/...]&ZOHO_ERROR_FORMAT=[XML/JSON]&authtoken=<your auth token>&ZOHO_API_VERSION=1.0

 

The control parameters such as "ZOHO_ACTION" is mandatory and have to be sent as part of the query string in the URL. Refer to Common Parameters document to know more about the possible parameters that could be passed in the Query String.

 

PARAMETERS TO BE PASSED VIA THE BODY OF POST REQUEST

Apart from the parameters passed in the Query string, additional information needed for specific actions (such as values of row in a Add Row operation etc.,) needs to be passed as POST parameters

 

<param1>=<value1>&<param2>=<value2>....

 

The parameters should be encoded in application/x-www-form-url encoded format (This is the default format used by any simple html form).
Note: In the case of importing csv files multipart/form-data format should be used. (This is the default format used by html forms that contain file type fields used for uploading files) 


 

Sample request 

The below URL adds a row in EmployeeDetails table in EmployeeDB database in
a CSV format.

 

https://<server_hostname>:<portnumber>/api/<abc@manageengine.com>/EmployeeDB/EmployeeDetails?
ZOHO_ACTION=ADDROW&ZOHO_OUTPUT_FORMAT=XML&ZOHO_ERROR_FORMAT=XML&
authtoken=g38sl4j4856guvncrywox8251sssds&ZOHO_API_VERSION=1.0

 

Sample POST parameter

Parameters for EmployeeDetails table in EmployeeDB database.

 

&Name=Gary&Date Of Birth=12-Jun-1980&Country=USA&Salary=10000

 


 

Response Format 

The response format of the API request is controlled by the ZOHO_OUTPUT_FORMAT query parameter passed in the request. Currently Analytics Plus supports XML and JSON response formats. CSV and PDF response formats are supported only for Export action.

 

XML FORMAT

The response will have the <response> tag as the root node. It might either contain a<result> or <error> node as it's child, but not both. The <result> node will be present under normal circumstances, whereas <error> node will be present in case of error conditions.

 

FORMAT 

<?xml version="1.0" encoding="UTF-8" ?>
<responseuri="/api/<loginemailaddress>/<databasename>/<tablename>" action="<specifiedaction>">
<result>
[specific XML response based on action]
</result>
</response>

 

JSON FORMAT

JSON format follows the same pattern as that of XML format.

 

FORMAT

{
"response":
{
"uri": "/api/<loginemailaddress>/<databasename>/<tablename>",
"action": "<specified action>",
"result": {[action specific properties]}
}
}

OTHER FORMATS 

Other formats such as CSV, PDF can be specified only when ZOHO_ACTION is EXPORT. These formats don't have any generic parseable header/footer. See this link for more details about these formats.

 


 

Sample Response : For ADDROW

Sample response to a request adding a row to the EmployeeDetails table in the
EmployeeDB database.

 

XML Format:

<?xml version="1.0" encoding="UTF-8" ?>
<response uri="/api/abc@zoho.com/EmployeeDB/EmployeeDetails" action="ADDROW">
<result>
<!-- All the columns in the row , including formula columns -->
<row>
<column name="Name">Gary</column>
<column name="Date Of Birth">12-Jun-1980</column>
<column name="Basic">10000</column>
<column name="Country">USA</column>
</row>
</result>
<response>

 

JSON Format:

{
"response":
{
"uri": "/api/abc@zoho.com/EmployeeDB/EmployeeDetails",
"action": "ADDROW",
"result":
{
"column_order":["Name","Date Of Birth","Salary","Country"],
"rows":
["Gary","12-Jun-1980",10000,"USA"]
}
}
}


 Error Handling

 

API execution could result in Error conditions. In such cases, you may follow the below steps to identify an error condition and to handle the same:
Check the http response code. If it is 4xx or 5xx (eg., 400, 500, 401 etc.,), then it is an error.
In case of error, the error information would be sent in the response body.
The format of the error content can be specified by the parameter ZOHO_ERROR_FORMAT. The value it can be either:XMLJSON

 

XML FORMAT

<?xml version="1.0" encoding="UTF-8" ?>
<responseuri="/api/<loginemailaddress>/<databasename>/<tablename>" action="<specifiedaction>">
<error>
[error details]
</error>
</response>

 

JSON FORMAT 

{
"response":
{
"uri": "/api/<loginemailaddress>/<databasename>/<tablename>",
"action": "<specified action>",
"error": {[error details]}
}
}


Sample error response : IMPORT DATA

 

Sample error response for import data in Table EmployeeDetails in the
database EmployeeDB

 

XML Format:

<?xml version="1.0" encoding="UTF-8"?>
<response url="/api/demouser/EmployeeDB/EmployeeDetails" action="IMPORT">
<error>
<code>7138</code>
<message>
Table EmployeeDetails is not present in the database EmployeeDB
</message>
</error>
</response>

 

JSON Format:

{
"response":
{
"url": "/api/demouser/EmployeeDB/EmployeeDetails",
"action": "IMPORT",
"error":
{
"code":7138,
"message": "Table EmployeeDetails is not present in the
database EmployeeDB"
}
}
}


Common Parameters in Query String of the API URL 

In this section we will discuss about the mandatory and optional parameters that could be passed in the query string of every API call.

 

MANDATORY PARAMETERS:

 

AUTH TOKEN

Auth Token is an unique token that authenticates the user to access the Analytics Plus Account.

 

Steps to generate authtoken
  • Authtoken can be generated by launching the URL- <Accounts URL>/apiauthtoken/create?SCOPE=ZROP/reportsapi
  • Accounts URL can be found in the application console, under Help icon --> Product info --> Miscellaneous details
  • Eg- https://steve-0430:8210/apiauthtoken/create?SCOPE=ZROP/reportsapi

 

ZOHO_ACTION

This parameter specifies the action to be performed by the API request. The sample values are:

 

ParameterDescription
 ADDROWTo add a row of data into a table.
 IMPORT

To import data in bulk into a table in CSV/TSV/Tabular Text formats

 UPDATE

To update existing rows in a table.

 DELETE

To delete rows in a table.

 EXPORT

To export table or report in different formats. 

 DATABASEMETADATA

To fetch information about the databases and the reports created within it, in your Analytics Plus account.

 

Note: Value of ZOHO_ACTION parameter should be in the same case(UPPER CASE) as given in this document.

 

ZOHO_OUTPUT_FORMAT

This parameter specifies the output format for the response. Following are the following supported formats:

  • XML

  • JSON

 

Incase ZOHO_ACTION is EXPORT then following additional formats are supported.

  • CSV

  • PDF

  • HTML

  • IMAGE

 

ZOHO_ERROR_FORMAT

Specifies the output format for the response in case an error occurs when trying to process the request. Following are the supported formats:

 

  • XML

  • JSON

 

ZOHO_API_VERSION

The API version of Analytics Plus based on which the application(service) has been written. This parameter allows Analytics Plus to handle applications based on the older versions. The current API version is 1.0

 

OPTIONAL PARAMETERS:

These parameters have to be sent in the body of the POST request.

 

ZOHO_DATE_FORMAT

This parameter can be used during Import of data, which has a date column, whose format is not properly identified by Analytics Plus.

Example: ZOHO_DATE_FORMAT=dd-MMM-yyyy
 

 

Share this post : FacebookTwitter