Overview

The Zannel Open API is a REST based webservices API, allowing programmatic access to Zannel's platform. Developers can build applications, widgets, web and mobile apps that act on behalf of the user or interact with the Zannel platform in new and interesting ways.

Accessing the API

The Zannel Open API is built on REST based principles, and strives to make interaction with the Zannel platform simple and consistent. Calls use the native HTTP methods for access and modifications, wherever possible. Some methods are publicly available, while some require authentication. Each service is clearly marked with authentication and authorization requirements. Any client that can perform basic HTTP commands can access the api. For example, you can use cURL or a web browser to browse new users or updates.

Retrieve updates via cURL:

curl http://app.zannel.com/api/browse/update.xml

Retrieve updates, via web browser visit:

http://app.zannel.com/api/browse/update.xml

Response Codes

The Zannel Open API uses HTTP status codes to signal success or failure. Below is a list of the HTTP status codes returned by the API:

Code	Response	Description
200	OK	The request succeeded, and the body of the response contains data.
202	Accepted	The request succeeded, but there is additional server side processing that must occur. This is returned only when a Video update is created. This status code signals that the video data was received, but that transcoding might still fail, and that the update might not be immediately available or visible from other webservices.
204	No Content	The webservice completed the operation successfully, but there is nothing to return in the response. This status code is often returned after deleting something.
400	Bad Request	The webservice cannot handle the request due to one or more possible issues: A required parameter is missing. A specified parameter has an illegal value. The maximum number of requests for these credentials has already been met (meter cap).
403	Forbidden	Valid credentials were provided, but do not allow access to this webservice. For example, attempting to access a private user's profile, when the provided credentials do not represent a friend of the user being accessed result in this exception.
404	Not Found	The resource represented by this webservice either does not exist or has been deleted. This can happen, for example, if user name is misspelled.
500	Internal Server Error	The server encountered an unexpected error and was unable to service the request. Let us know about it in the "Discussions" section of this group.
501	Not Implemented	The requested HTTP method is not supported by this webservice. This can occur, for example, by calling POST on a webservice that only supports GET (ie read) operations.

Formats

Each webservice in the Zannel Open API can return results in one of multiple formats. Currently, all services support output in XML and JSON formats. Additional formats will be forthcoming. Example webservice outputs can be seen [here]. To specify the format of results, simply set the extension of the call to the appropriate format. For example:

Retrieve users in XML format:

http://app.zannel.com/api/browse/user.xml

Retrieve users in JSON format:

http://app.zannel.com/api/browse/user.json

Authentication

Most webservices in the Zannel Open API require authentication. Each service states whether it requires authentication. Zannel does not have separate developer keys for accessing API methods that require authentication. Instead, the API is accessed using the same credentials used to access the Zannel web or wap site (username and password).

The API supports 3 methods of authentication:

HTTP Basic Auth
Parameter based - Add "authuser" and "authpass" parameters to the webservice call, with the user name and password, respectively.
Cookie based - Use the standard "user" cookie provided by logging into the Zannel web or wap site. For web or wap apps, if the user is already logged into Zannel, API authentication will happen automatically.

Successful authentication via Basic Auth or Parameters will also return a HTTP cookie that can be used with "Cookie based" authentication, as described above.

Metering

Calls to any webservice that requires authentication are metered. A particular set of credentials cannot make more than 100 calls per hour to a metered service. Calls that exceed the metering cap will receive a HTTP 400 error.

Caching

Zannel caches the responses to some webservices in the Zannel Open API to improve performance. Any webservice that does not require authentication may be cached. Currently, any webservice that requires authentication is not cached.

Media

The Zannel Open API has urls to videos and images on User and Update results. Each video or image has preview pics in 3 sizes. The sizes were chosen to be useful for both web based and mobile based applications. In addition, User and Update results always have a zannelurl attribute. This url detects the user agent of the caller and sends them, via an HTTP 302 redirect, to the Zannel web or wap page to view the entity on Zannel's site. Image and zannelurl access are not metered. For example:

The zannelurl of the Zannel user, from the api:

http://app.zannel.com/api/redirect/user/zannel

If the caller is a web browser, a redirect is sent to:

http://www.zannel.com/user.htm?name=zannel

If the caller is a wap browser, a redirect is sent to:

http://wap.zannel.com/channel.htm?id=zannel

These urls may also take a "short" form. For example the zannelurl of an update, from the api:

http://www.zannel.com/t/GJ59U8XNOT

The appropriate redirect will take place as above.

Help

Questions or bug reports can be posted in the "Discussions" section of this group. In addition, Zannel developers can often be found in the #zannel IRC channel on irc.freenode.net

Services

Here is a complete list of the services the Zannel API currently offers:

Browse Webservices

Store Services

Store Service

User Services

Update Services

Info Services

All Info webservices return in a standard format. The "key" attribute should be used as the parameter value when submitting to Zannel. The "description" attribute or tag text is non authoritative, but can be used for displaying options to the user. The one exception to this is the Zannel Url webservice, which uses the same format, but simply returns a set of urls for getting to places on the Zannel web and wap sites.

Webservice Access Level

Our webservices have a certain access level, based on the operation that you may be calling them. Here is a list of our current access levels.

Access Level	Description
PUBLIC	Can be called by anyone, and does not require any form of authentication. All public webservices are cached, so may not reflect changes to the underlying data immediately. Example: Browse Updates webservice.
MEMBER	Requires authentication. Any Zannel user can call this webservice and get results back without restrictions. Example: GET User webservice
FRIEND	Requires authentication. If the user who owns the data is public, this is the same as a member webservice. If the user who owns the data being called is private, then the caller must either be the user who owns the data, or a friend of the user who owns the data. Example: GET User Updates webservice, on a user with a private profile.
OWNER	Requires authentication. Only the user who owns the data may call this webservice. Example: POST User webservice.

Paged Webservices

Many of the webservices can return long list of results. All services where this is a case take a common set of parameters to facilitate paging:

parameter	description
offset	the number of items into the result to start the return results. Must be 0 or greater. If not specified, defaults to "0"
length	the number of items to return, starting at the offset. Must be a positive number between 0 and 20. If not specified, defaults to "10". If there are less than "length" number of items available, the available number of items is returned instead.

Bindings and Example Applications

See here for apps others have built and for language bindings (client side libraries others have built to make using the Zannel Open API even easier).

Version:

User Services	Nov 20
Store Services	Nov 16
Update Services	Jun 15
API Output - Update Service	May 14
API Output - Browse Services	May 12
Overview	May 7
API Output - User Services	May 5
applications and language bindings	May 13
Browse Services	Mar 13
icon.png	Feb 28