|
|
|
|
Zoho
Show - Data APIs
Zoho Show provides REST style Data APIs which
allows client applications to view, list, edit, save, import, export and perform
a host of useful operations on their presentations. Thus, these APIs provide an
easy way to integrate Zoho Show presentations 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 Presentations 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. Zoho Data APIs based on XML-RPC
specification can be found here.
To get started
with the Show REST APIs, please refer our API Reference.
API URL
For accessing the Zoho Show Data
API, users need to pass a couple of additional query parameters. These
parameters are:
For more on how to request for an API Key and
generate Ticket ID, please click here. Once the requisite API Key and Ticket
ID is acquired, users should use the following format mentioned below to access
the API methods:
http://show.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 Show APIs:
1.
Read Operations:
For read like
operations, HTTP GET calling convention is used.
Example -
/api/private/xml/presentations -- this will fetch the list of presentations
available in your Zoho Show account.
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 presentations
available in your account the url
"http://show.zoho.com/api/private/xml/presentations" can be used.
--
URIs for exposing public details start with "/api/public/"
For example,
to get the list of public presentations in ZohoShow the url
"http://show.zoho.com/api/public/xml/presentations" can be used.Moreover these
set of APIs do not require authentication and hence users need not pass 'ticket'
as query parameter.
2. Write
Operations:
For write operations like renaming or editing/saving a
presentation, 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://show.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://show.zoho.com/api/public/xml/presentations" will return the
list of publicly available presentations in XML format.
--
"http://show.zoho.com/api/public/json/presentations" will return the list of
publicly available presentations 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 Zoho Show,
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 generalized XML
error response is mentioned below:
For a full list of error codes, please
click here.
|
Document Saved Successfully
|
|
|
|
|
|
|
