Home / Zoho API Developers Guide / Data API Reference

Data API Reference

Tags:  

Data API Reference for Developers

Zoho provides REST style Data APIs which allows client applications to view a list of documents for a particular user, get the content of a document, edit them, upload/download document, grant/revoke sharing privileges for a document, tag documents in folders, and publish document for the external world. Thus, Data APIs provide an easy way to manipulate data and files stored in different Zoho Office productivity applications like Writer, Sheet and Show.

Developers task have been made easier with the introduction of REST based Data APIs as it enables them to access all the document-related information by using a simple HTTP invocation. Using REST, developers can obtain domain specific data by pointing a URI to a specific location. In other words, developers can interact with a URI (e.g. https://sheet.zoho.com) through a pre-defined set of methods and receive standard HTTP responses in return. Now, let's have a detailed look at the REST request and response formats :

REST Request Format :

As discussed here, developers need to send two additional parameters, while sending the REST request. The parameters are "apikey" and "authtoken".

Once the required parameters (apikey & authtoken) are obtained, developers can use the following URI format for accessing the Data API methods :
https://<servicename>.zoho.com/api/<access>/<format>?apikey=[your_api_key]&authtoken=[your_auth_token]&scope=DataAPI
Where :
  • servicename: Name of the Zoho Service (Writer, Sheet or Show)
    possible values : "writer.zoho.com", "sheet.zoho.com" & "show.zoho.com"

  • access: The access parameter can take two possible values - "private" and "public".

    • URIs for manipulating user specific details start with "/api/private/".
      Example: To get a list of documents for a Zoho user, the URI "https://writer.zoho.com/api/private/xml/documents"
      can be used
    • URIs for getting public details, that are made available for everyone to view, start with "/api/public/"
       Example: To get a list of public spreadsheets in Zoho, the URI "https://sheet.zoho.com/api/public/xml/books" can be 
      used.
  • format: The format parameter takes two possible values : "xml" and "json". Depending on the format value specified in the request URI, Zoho will return either  XML or JavaScript Object Notation(JSON) as a response.

  • HTTP calling conventions : GET and POST

    • For "read operations", HTTP GET is used.
    • For "write operations", HTTP POST is used

REST Response Format :

Currently, Data APIs support the following response formats :
  • XML
  • JSON
    • JSONP (JSON callback)
Response Structure

The response will have a <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.

Thus, normal response will be of the form :
<?xml version="1.0" encoding="UTF-8" ?>  
<response uri="/api/private/xml/documents">
<result>
     [specific XML response here]
</result>
</response>

In case of error conditions - for example, referring to a document not present in Zoho Writer - the response will be of the form :
<?xml version="1.0" encoding="UTF-8" ?>
<response uri="[request URI]">

<error>
<code>[error code]</code>
<message>
     [Error Message]
</message>
</error>

</response>

In the subsequent sections, we will be provide details of the different types of methods available for Writer, Sheet and Show.


    Post a comment

    Your Name or E-mail ID (mandatory)

    Note: Your comment will be published after approval of the owner.




     RSS of this page