Introduction

ToTheZeroth News is a cloud-hosted RSS/Atom feed reading service. In order to make it as accessible as possible, it is equipped with an open API (application programming interface) that developers can use in their applications. It is based on HTTP 1.1 and developed using the principle called REST. Information is transmitted in the JSON format, using the HAL extension for linking.

If a lot of the terms in the first paragraph sounded intimidating, and you are now finding yourself with four new browser tabs and trying to grasp all aspects of the technologies, then you are probably doing this the wrong way. Getting the hang of a REST interface is much easier if you just try it. And as long as you know how to create and send HTTP requests, that's as easy as it gets. Just send a GET request to:

The response will give your application the links it needs to proceed. This documentation will tell you the rest.

Resource structure

The API is built around a number of resources which the client can read, and in some cases create, update and delete. Resources have certain properties, they can have other resources embedded in them, and they can link to other resources. A convention in this API is that any resource whose name is a plural noun is a "collection" (although it's still technically a resource, too).

Each resource (and collection) has a specific documentation page; see the links to the left.

Authentication

With the exception of the entry point, "feed info" and "users", all resources require the client to authenticate as a certain user by means of HTTP Digest Authentication. Unless valid credentials have been supplied in the Authorization header, the server will respond 401 Unauthorized with a challenge in the WWW-Authenticate header.

At this point, or before it, the user must supply an e-mail address and a password to the client. These, together with the realm from the "users" collection (or from the WWW-Authenticate header), are hashed into a lower-case hexadecimal string known as HA1 (use the algorithm specified in the challenge). As long as the user does not change e-mail address or password, the HA1 will never change and it may be stored by the client. The HA2 hash must be computed for each request, using information supplied in the WWW-Authenticate header. The client may use any string for the cnonce value. The value of nc, on the other hand, MUST be 00000001.

So, how RESTful is it?

Fairly RESTful. Definitely more RESTful than the multitude of APIs that call themselves RESTful but simply aren't. But there are several compromises, which may be frowned upon by some purists:

• At times, the client needs to remember more than just the result of the last request. For instance, DELETE returns 204 No Content without providing any links. (It is possible in such cases, of course, to start over from the entry point, but that's seldom the smoothest approach.)
• Numerical IDs are sometimes used in URI templates, rather than having (extremely many) ready-made links to everything. This adds to the flexibility and usefulness of the API, but also to the client's need to remember more than one response.
• The multi-post functionality conflicts at least partially with the "one request, one resource" idea. (Multi-post was implemented because it was needed for OPML import, and using it is strictly optional.)
• The documentation is only written in these HTML pages. There is no machine-readable version.

URI structure

For largely aesthetic reasons, the URI structure is very transparent and lends itself to URI guessing and hard-coding. Do not engage in such activity. You should follow the HATEOAS links instead; that's what they are for. As with any RESTful API, any breakage of client functionality due to changes in the URI structure is the client's problem.