JSON

Zoho Writer API
Get started with the Writer APIs

Zoho Writer provides REST style Web APIs which allows client applications to view, list, edit, save, import, export and perform a host of useful operations on their documents. Thus, these APIs provide an easy way to integrate Zoho Writer documents into your application.

The REST specification is often used to describe any simple interface that transmits domain specific data over HTTP without an additional messaging layer such as SOAP. An important concept in REST is the existence of resources (sources of specific information), each of which can be referred to using a global identifier (a URI). In order to manipulate these resources, components of the network (clients and servers) communicate via a standardized interface (e.g. HTTP) and exchange representations of these resources (the actual documents conveying the information).

The calling conventions employed over here for these APIs are GET and POST depending on the kind of operation (Read/Write) that is being performed. In return the user gets a formatted XML/JSON response from the called method.

The previous version of our APIs were loosely based on RPC style. The Web APIs based on XML-RPC specification can be found here.

To get started with the Writer REST APIs, please refer our API Reference.

API URL

For accessing the Zoho Writer API the users need to pass a couple of additional query parameters. These parameters are:

API Key
Ticket

Please refer here on the process of getting the 'API Key' and 'Ticket'. Once the requisite API Key and Ticket is acquired, the users should use the following format mentioned below to access the API methods:

http://export.writer.zoho.com/api/xml?apikey=[API Key]&ticket=[Ticket]

REST Request Format

The request format will vary depending on the type of operation (Read or Write) being performed by the APIs. The most important HTTP methods are GET and POST. GET calling convention is analogous to READ operation whereas POST method is used where data is to be written or modified. The following basic operations are performed using the Zoho Writer APIs:

1. Read Operations:

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

Example - /api/private/xml/documents -- this will fetch the list of documents available in your Zoho Writer account.

2. Write Operations:

For write operations like renaming or editing/saving a document, HTTP POST calling convention is used.

REST Response Format

The type of response being generated will depend on the 'format' specified in the request URL.

The URL will be of the form

http://export.writer.zoho.com/api/private/[format]/...

Currently, the following response formats are supported

XML
JSON
- JSONP (JSON callback) support is available.

For example,

-- "http://export.writer.zoho.com/api/private/xml/documents" will return the list of available documents for a user in XML format.
-- "http://export.writer.zoho.com/api/private/json/documents" will return the list of available documents for a user 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="/api/private/xml/documents">

	<result>
        	[specific XML response here]
	</result>

  </response>

In case of error conditions, say we are referring to a document not present in ZohoWriter, the response will be of the form

<?xml version="1.0" encoding="UTF-8" ?>
<response uri="<e.g. [/api/private/xml/documents]>">

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

</response>

Error Codes and Messages

The list of exceptions that you will get while accessing the API methods are basically segregated into two categories -

General - This entails authentication errors as well as internal server errors while processing the request.

Input - This error may occur as a result of user missing out on providing mandatory arguments for the method, incorrect parameter values etc.

The error report will be in the form of HTTP error code and an XML error response. The list of error codes and a generalised XML error response is mentioned below:

Error Codes

The list of HTTP error codes are tabulated below:

Code	Category	Description
1400	General	Error occurred while parsing the URI
1401	General	Authentication failed because of invalid "ticket"
1404	General	Document not found
1405	General	No such Method. Incorrect method name
1890	General	The "apikey" specified in the request is invalid.
1822	General	Authentication failed for GET method
1833	General	Server Error while processing the request

1832	Input	Missing argument error. Mandatory arguments, required for processing this request is missing
1416	Input	Specified value is not consistent for the present request. Request range not satisfied.
1801	Input	Document name specified should not contain special characters.
1500	Input	Unsupported Media Type, Upload Failed please try again with proper input.
1802	Input	Invalid image name. Name specified should not start with a number

1800		No documents in the trashed list
1803		Please specify the document content type
1804		Tag-name not found. No such tag exists for the document
1805		No such document exist for the given tag-name.
1806		No such document found in the shared list
1807		The document is already trashed.
1810		Tag-name already exists for the document.

API Reference

To get started with the Writer REST APIs, please refer our API Reference.