1.API usage:

• First, the workbook to be edited should be uploaded into the ZohoSheet server. Once the workbook is uploaded, the Zoho Sheet editor for editing that workbook can be opened up. The third party application provider also have the option of doing the above two steps(uploading and opening the workbook in editor) at one go or they can be done seperately.

• the third-party server can upload the workbooks into the Zoho Sheet server using either a multi-part form submit or normal form submit.

• The workbook can be modified using the editor. Once 'Save' button provided in the editor is clicked, the updated workbook will be pushed back to the third party server (will be reffered as 'remote server' henceforth).
  • the updated versions of the workbook will be pushed to the remote server using a multi-part form submit.
    
    
• On closing the editor,the transient copy of the workbook maintained in the Zoho Sheet server will be cleaned up. This is the default behaviour. However, it's also possible to persist that workbook in Zoho Sheet server itself, for if that workbook needs to be edited again, then there is no need for uploading the workbook again to the Zoho Sheet server.

2. Uploading workbooks

To upload a workbook, the following URL api should be used. Other required details should be sent as a form submit along with this url.


Apart from apikey, the above URL api can have following two query parameters

a. output:

    This parameter decides the format of the output. On passing 'editor' as the output value, Zoho Sheet editor will be opened up directly for editing.

The possible values for query parameter 'output' are

• editor -- The Zoho Sheet editor will be opened up directly
• url -- outputs a URL which contains a unique Id representing the workbook to be edited

by default the response will be a URL


b. lang:
   
    This parameter decides the language supported in Zoho Sheet editor.
   
The possible values for the query parameter 'lang' are

• en -- English
• fr -- French
• de -- German
• js -- Japanese
• es -- Spanish
  

The default value for this parameter is 'en'. Moving forward other languages will be supported.

Response Format for URL request:

URL=[url value]

WARNING=[warning message, if any]

RESULT=[TRUE/FALSE]

RESULTfield indicates the status of the action

Sample Response:

RESULT=TRUE
URL=http://sheet.zoho.com/editor.im?doc=3000000012001

Suppose, the workbook to be uploaded is available in a url accessible to Zoho Sheet server, 'normal form submit' can be used. In this case, it's sufficient to specify only the url, from which Zoho Sheet can download the workbook.

Else, 'multi-part form submit' can be used by the remote server. Here, the file to be uploaded is sent as the POST content.

Both the methodologies are described below..

2a.Using multi-part form submit:

To upload the workbook to Zoho Sheet server, submit a multi-part form-data to Zoho Sheet with the following fields

Field	Description
content	actual workbook content
filename	filename of the workbook with extension (supported formats : .xls, .sxc, .csv)
id	unique handback id that will be handed back by Zoho Sheet server while pushing the updated versions of the workbook
format	the format in which workbooks should be pushed to the remote server (supported formats: .xls, .sxc, .csv )
persistence(optional)	if this parameter is not passed or set to false, the document uploaded to ZohoSheet will be editable only once. When the user exits the browser window, it will be automatically deleted from ZohoSheet server
saveurl	[REMOTE SERVER SAVE URL] - The Web URL should be a service that fetches the content of the updated document and saves it to the user specified location.

* document can be pushed from remote server to Zoho Sheet in one format and can be saved in different format also

Sample multipart form:

<form method="POST" action="http://sheet.zoho.com/remotedoc.im?output=editor" enctype="multipart/form-data" target="_self">

File : <input type="file" name="content" size="38"> <br>

<input type="hidden" name="saveurl" value="[REMOTE SERVER SAVE URL]">

<input type="hidden" name="id" value="12345678">

<input type="hidden" name="format" value="xls">

<input type="submit" value="Edit" class="divbutton" name="submit">

</form>

* In order to edit a workbook in Zoho Sheet, it must be submitted as multi-part form data either from the client side or it can be done as a emulated multi-part form submission on the server side of the remote server.

2b.Using normal form submit:

The form data will have following fields.

Field	Description
url	url from which Zoho Sheet can fetch the document
filename	filename of the workbook with extension (supported formats : .xls, .sxc, .csv)
id	unique handback id that will be handed back by Zoho Sheet server while pushing the updated versions of the workbook
format	the format in which workbooks should be pushed to the remote server (supported formats: .xls, .sxc, .csv )
persistence(optional)	if this parameter is not passed or set to false, the document uploaded to ZohoSheet will be editable only once. When the user exits the browser window, it will be automatically deleted from ZohoSheet server
saveurl	[REMOTE SERVER SAVE URL] - The Web URL should be a service that fetches the content of the updated document and saves it to the user specified location.

* In order to edit a workbook in Zoho Sheet, it must be submited as form data either from the client side or it can be done as a emulated form submission on the server side of the remote server.

Sample form

<form method="POST" action="http://sheet.zoho.com/remotedoc.im?output=editor" target="_self">

<input type="hidden" name="url" value="[REMOTE DOCUMENT URL]">

<input type="hidden" name="saveurl" value="[REMOTE SERVER SAVE URL]">

<input type="hidden" name="id" value="12345678">

<input type="hidden" name="format" value="xls">

<input type="submit" value="Edit" class="divbutton" name="submit">

</form>

3. Saving the document in a remote server

The workbook which is edited in the Zoho Sheet editor will be pushed to the remote server using multi-part form submission from the Zoho Sheet Server. The URL to which it will be pushed is specified at the time of uploading the document from remote server(refer 'saveurl' form field above).

Field	Description
format	the format of the pushed workbook (supported formats : .xls, .sxc, .csv)
content	content of the workbook
filename	filename of the workbook with extension
id	unique handback id that was specified while uploading the workbook from the remote server

* the remote server should understand multi-part form submission with the above fields in order to receive the updated versions of the workbook.


Zoho API is an easy way to integrate Zoho Services into your application. Do have a go at the APIs by signing up for the key now. If you have any further questions regarding the Zoho API, write to us at api@zohocorp.com.

Note : It is mandatory to have the remote server address set to port number 80 for all the upload and download operations.