API Home>> Sheet

JSON

Zoho Sheet API Sheet API Reference

ZohoSheet provides REST style web APIs which allows a client application to view, modify, upload, download and perform host of other useful operations on their workbooks. Thus, these APIs provide an easy way to integrate ZohoSheet workbooks into your application.

The previous version of our APIs were loosely based on RPC style. But the current version is based on REST style as it's more easy to use. The old APIs are deprecated (but functional) now. It's API reference can be found here.

To straight away get started with our APIs, please refer our Sheet API Reference.

Do read further for a high-level overview about our web APIs.

REST Request

As discussed here, while sending the REST requests, two additional parameters needs to be sent. They are 'apikey' and 'ticket'.

a.Read Operations:

For read like operations, HTTP GET/POST calling convention is used.

The read APIs are further segregated into user specific details (Private) and details that are made available for everyone to view (Public).

URIs for manipulating user specific details start with "/api/private/"
For example, to get the list of workbooks available in your account the url "http://sheet.zoho.com/api/private/xml/books" can be used.
URIs for exposing public details start with "/api/public/"
For example, to get the list of public workbooks in ZohoSheet the url "http://sheet.zoho.com/api/public/xml/books" can be used.Moreover these set of APIs do not require authentication and hence users need not pass 'ticket' as query parameter.

b.Write Operations:

For write operations like renaming or updating a workbook, HTTP POST calling convention is used.HTTP GET is not supported for write operations.

REST Response

The type of the response format will be based on the 'format' specified in the request URL.

The URL will be of the form

http://sheet.zoho.com/api/[private or public]/[format]/...

Currently, the following response formats are supported

XML
JSON

JSONP (JSON callback) support is available.

For example,

-- "http://sheet.zoho.com/api/public/xml/books" will return the list of publicly available workbooks in XML format.
-- "http://sheet.zoho.com/api/public/json/books" will return the list of publicly available workbooks in JSON format.

a.Response Structure

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.

Thus, normal response will be of the form


<?xml version="1.0" encoding="UTF-8" ?>
  <response uri="[request URI]">
	<result>
[specific XML response here]
	</result>
  </response>

In case of error conditions, say we are referring to a workbook not present in ZohoSheet, 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 description] </message>
	</error>
  </response>

Error Codes and Messages

The list of error codes and their corresponding descriptions are listed below:

Error Codes

Code	Category	Description
2500, 2501, 2502, 2503	General	Internal Server Error while processing the request
2890	General	The "apikey" specified in the request is invalid
2891	General	Bad request URI.
2401	General	Authentication failed because of invalid "ticket"
2402	General	The specified operation (e.g. HTTP GET or POST) is not supported for this request

2831	Input	Mandatory arguments, required for processing this request is missing
2832	Input	Value specified for a parameter is wrong
2833	Input	Value specified for a parameter is of wrong type
2835	Input	Specified value is not consistent for the present request.

2851		The 'workbook Id' specified in the request doesn't exist in your account
2852		The 'workbook Id' specified in the request is trashed and not accessible
2853		The 'workbook Id' specified in the request is shared to you and not accessible
2854		The 'workbook Id' specified in the request is locked (for editing) by other user and not accessible
2855		The 'workbook Id' specified in the request cannot be saved, as someone else has updated it since your last retrieval

API Reference

To get started with our APIs, refer Sheet API Reference.