API Specification

Zoho Analytics 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/report/dashboard in a Zoho Analytics workspace 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.

• Server URI
• Request Format
• Response Format
• Error Handling

Server URI

The following server URI are available for Zoho Analytics. Choose the server URI based on your data centre.

Request Format

All API requests should be placed as HTTPS POST request. A 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
• Authorization Using OAuth 2.0.
• Parameters sent via the body of the POST request.

URI

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

https://<ZohoAnalytics_Server_URI>/api/<OwnerEmail>/<WorkspaceName>/<ViewName>

It consists of the following parts

• ZohoAnalytics_Server_URI: Server URI varies for each data centres. Click here to check the available Server URIs in Zoho Analytics.
• OwnerEmail: This should be the Zoho Login Email Address of owner of the organization where the workspace is present. (e.g., abc@zoho.com)
• WorkspaceName: This should be the name of the workspace on which the API is to be executed. (e.g., EmployeeDB)
• ViewName: 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]&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.

AUTHORIZATION USING OAUTH 2.0

Access token have to be passed in the header for authorization purpose in the format given below.

Authorization: Zoho-oauthtoken <access_token>

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

<param>1=<value>1&<param2>=<value2>....

The parameters should be encoded in application/x-www-form-urlencoded format (This is the default format used by any simple html form).

Response Format

The response format of the API request is controlled by the ZOHO_OUTPUT_FORMAT query parameter passed in the request. Currently Zoho Analytics 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" ?>

<response uri="/api/EmailAddress/WorkspaceName/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/EmailAddress/WorkspaceName/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.

Error handling

API execution could result in Error conditions. In such cases, follow the below steps to identify an error condition and 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:
  • XML
  • JSON

XML FORMAT

<?xml version="1.0" encoding="UTF-8" ?>

<response uri="/api/EmailAddress/WorkspaceName/TableName" action="<specifiedaction>">

<error>

[error details]

</error>

</response>

JSON FORMAT

{

"response":

{

"uri": "/api/EmailAddress/WorkspaceName/TableName",

"action": "<specified action>",

"error": {[error details]}

}

}