The Second Stone · 10 June, 08:18 PM

So today Dare takes NewsGator to task for the (mis) design of the NewsGator REST API. At one time, some people thought it wasn’t too shabby, but I guess everybody’s tired of beating up on Flickr and Bloglines, and so it’s NewsGator’s turn. I kind of feel a certain ownership of the thing, since I was the original designer. Now that baby’s moved on to foster parents, and I should probably just let it go, but some of the sins Dare mentions might be mine. It’s been a couple of years, and I can’t exactly recall. But in the interest of absolution, here’s what I remember about designing the REST API.

In light of some of the But this is just POX crap! accusations, here’s some backstory: the original version of the REST API was created concurrently with the SOAP API, but it was never released. This was a good thing; the original (unreleased) REST API was RPC/POX over POST, mainly because I was looking at the Bloglines API for guidance. So that work benefited from a cooling off period. Dare’s not been exactly fair: he’s highlighted the places where the NG REST API falls down, but he hasn’t highlighted the places where it does the right thing. There are some places, right Dare?

Incidentally, the guiding light behind the whole thing was Joe Gregorio’s Aggie application; which had the option to put in the URI of an OPML subscription list. Aggie was my first experience with sync in a feed reader, and a lot of my thinking around this design went back to Aggie: how can I create an API that will work for a brain-dead simple aggregator? I wasn’t always successful, but that was my primary design constraint.

Dare’s dead on on his section “What Should a Feed Reader’s REST API Look Like?” – “There are two main resources or data types in a feed reader; feeds and subscription lists.” NewsGator actually defines a few other resources: Locations, Folders, and various other types that were added later. Indeed, the NG API exposes endpoints Location.aspx, Subscription.aspx, Folder.aspx and Feed.aspx. But Dare rightly calls out a number of instances where the NG API puts a verb into the URI. I should point out that it’s not necessarily practical to rely on PUT and DELETE; as not every client is capable of using these verbs; as I’ve noted before sometimes the issues are subtle. But putting the verb into the URI is not the answer; in these cases, putting the verb into the payload is a less bad solution.

For sin #2, not providing a consistent interface, this was actually one of the big design changes between the pre-release and public-release versions of the API. Originally, I was encoding most of the parameters in POST as ordinary application/x-www-form-urlencoded data. My big realization was that if a GET returned an OPML document, then the POST should accept an OPML document – endpoints should be reflexive on their input and output. So for the most part, the NewsGator REST API does this. Dare points out one example where it doesn’t (given that it also encodes an operation in the URI, is that surprising?) However, in some cases, a response isn’t always necessary: the client should expect a certain state to result from an operation and if the server’s merely going to tell the client what it already knows (i.e. I added a folder, therefore I know what the new folder structure is going to be), the server can eliminate the response and rely on the response code to tell the client whether the operation worked. The one issue would be with concurrent updates from other sources – it’s possible that state could change on the server and the client would have to do a GET to find out about these changes. Still, I’m not sure that necessitates returning a response; as an application developer, I think it’d be confusing to get back a totally unexpected state change from an operation.

Dare mentions AtomPub as a candidate protocol for this application. I’m not so sure about using AtomPub for a feed reader API; I haven’t looked closely enough at it, but it’s really intended more for publishing and I have a feeling that it would be a poor fit; my gut feel is that you’d be forcing a square peg in a round hole with AtomPub in this situation. It’s also worth noting that at the time of the design, Atom 1.0 was not yet released and AtomPub was nowhere near release.

I also want to point out Dare’s statement “You will want full Create, Retrieve, Update and Delete operations on the subscription list. So you will need the full complement of supporting POST, GET, PUT and DELETE on subscription lists.” This isn’t exactly how you’d want to look at the HTTP verbs, as the CRUD analogy extends only so far. What you’re after is a description of the state of the application. Hypermedia is the engine of application state, after all. It all comes back to the URIs. If your URI’s don’t describe resources, it ain’t REST. If your resources don’t link to each other, it probably ain’t REST.

— Gordon Weakliem

---

Comment

  1. AtomPub extended to allow creation of workspaces sounds like the perfect match for a feed reader API in my humble opinion.

    — Asbjørn Ulsberg · Jun 12, 05:50 AM · #

  2. I’m going off memory and not consulting the spec, but isn’t atom:content or atom:summary required in Atom? You could repurpose that element or just send empty content but that’s what I mean by abusing the spec.

    — Gordon Weakliem · Jun 18, 04:10 PM · #

Commenting is closed for this article.