Skip navigation

This is Volume 40 of This week in REST, for September 12 2011 – November 16 2011. For more information on this blog see this post. If I missed an interesting blog post, discussion or paper – just e-mail me the links, tweet or leave a comment on the latest blog post. Thanks!

Around the Web

Web API Design Cookbook – “This document captures common practices in designing APIs that fit well into the Web platform as a whole, using WebIDL”

What the Web is and is not – “I’m beginning to see that some parts of the Web we take for granted are not what actually defines it. The Web is not HTML, CSS, and JavaScript. It’s not DOM, SVG, WebGL, PNG, or Flash. The Web is really just HTTP over TCP/IP. What gets transported over HTTP does not define the Web.There is, however, one other characteristic that does define the Web, and that is the humble hyperlink. Links are a feature of HTML, but they are not limited to HTML. Links are the connections that give the Web its name, and links are the biggest thing missing from native platforms.” (by Joe Hewitt)

The web interface should be radically refactored – “The Web API conflates two conflicting goals: serving developers by supporting a wide and growing suite of functionality, and providing applications with an isolated execution environment. We propose to split the API into two levels of interface: a low-level interface that governs the relationship between the application and the browser, and a set of high-level interfaces that govern the relationship between the application and its developer. We delineate a tiny set of properties needed by the low-level interface. We argue that this restructuring provides significant benefit to both developers and users.” (by Jon Howell, John Douceur, Bryan Parno)

hypermedia affordances – “right now i am of the opinion that a single set of aspects of hypermedia affordances can be identified. that this set would be universal to all hypermedia designs; no matter the protocol used (HTTP, FTP, etc.), the data format used (HTML, JSON, etc.). and that set of aspectsshould be enough to “construct” any hypermedia control needed in order to support a particular action in a distributed application.” (by Mike Amundsen)

Prefer Header for HTTP – “This specification defines an HTTP header that can be used by a user-   agent to request that certain behaviors be implemented by a server   while processing a request.” (IETF draft by J. Snell)

Using Hypermedia Services for Systems Integration – (presentation) “Tim Ewald explains why hypermedia is good for system integration through services –providing support for evolution, service request routing, and application recovery-, and how to build such services. ” (by Tim Ewald)

Cool URIs and Integration – “A key design aspect that made the very success of the World Wide Web possible was the removal of the referential integrity constraint from the hypermedia paradigm. In a system of the scale of the Web the problem of ensuring that no hyperlink would ever be broken cannot be solved and the only way to make the system work was to relax the constraint.” (by Jan Algermissen)

Creating Resources with GET/PUT – “creating resources the RESTful way can be done with either PUT or POST, with PUT expecting that the URI of the created resource is known in advance (by the client issuing the request). semantically, the difference is that PUT is idempotent and thus can be repeated safely, whereas POST is non-idempotent and thus cannot be repeated. a PUT can be repeated because after creating a resource, a repeated PUT will simply overwrite the resource with the same representation, whereas a POST always is directed towards some factory resource, and thus repeating it would create a duplicate, which should be many cases, clients do not know the URI of the new resource, so the PUT approach cannot be used. the problem with the simple POST model is that clients have a hard time figuring out what to do when the POST request fails (e.g., the HTTP library says something went wrong).” (by Erik Wilde)

TAG f2f04 Nov 2011 – Minutes from the W3C TAG face-to-face meeting in November.

RESTful Web Service Discoverability, part 4 – “Discoverability of an API is a topic that doesn’t get enough well deserved attention, and as a consequence very few APIs get it right. It is also something that, if done right, can make the API not only RESTful and usable but also elegant.To understand discoverability, one needs to understand that constraint that is Hypermedia As The Engine Of Application State (HATEOAS); this constraint of a RESTful API is about full discoverability of actions/transitions on a Resource from Hypermedia (Hypertext really), as the only driver of application state. If interaction is to be driven by the API through the conversation itself, concretely via Hypertext, then there can be no documentation, as that would coerce the client to make assumptions that are in fact outside of the context of the API.”

Web API Versioning Smackdown – “The answer is that there is no one answer; there are lots of different mechanisms in HTTP to meet the goals that people have for versioning.However, there is an underlying principle to almost any kind of of versioning on the Web; not breaking existing clients.The reasoning is simple; once you publish a Web API, people are going to start writing software that relies upon it, and every time you introduce a change, you introduce the potential to break them. That means that changes have to happen in predictable and well-understood ways.” (by Mark Nottingham)

URI construction: give it a REST – “Picture the scene: you’ve just updated your product’s REST API. You’ve added lots of new features, revamped the URI structure and you’re excited for your clients to start using it.One of these two things will happen within the hour:Your support line will ring off the hook with angry customers screaming about how none of their applications are working anymore, and how they’re going to wring your neck for breaking their systems at the worst possible time.Everything works great and your customers send you chocolates in gratitude for the new features.The problems in #1 will occur if your customers do any kind of URI construction in their REST API client applications. That innocuous “revamping” of your URI structure has just broken all the clients who were tightly bound to the exact format and layout of your old URIs.” (by Brian Kelly)

Webmachine: a Practical Executable Model of HTTP – (presentation) “Justin Sheehy details Webmachine, a RESTful toolkit for writing well-behaved HTTP applications, helping developers to deal with the complexities of an HTTP-based application. ” (by Justin Sheehy)

APIs are for human beings (too) – “Computers don’t care about API design. Convenient serialization formats, sane parameter names, and a RESTful interface mean nothing to a robot.  These aspects of an API are not meant for a machine, they’re meant for you – the developer.  APIs should be for human beings first and computers second.” (by Frank Stratton)

How REST replaced SOAP on the Web: What it means to you – ” The idea of reuse and composition made SOA an attractive proposition that sent thousands of organizations on a very challenging treasure hunt. We have since read SOA’s obituary and its resurrection with many stories of woe peppered with some success, but with very few achieving the holy grail of SOA. Meanwhile, the web has essentially become a service oriented platform, where information and functionality is a available through an API; the Web succeeded where the enterprise largely failed.This success can be attributed to the fact that the web has been decentralized in its approach and has adopted less stringent technologies to become service oriented.” (by Ross Mason)

I Hate HatEoAS – “For something that’s supposed to be THE defining characteristic of REST, it could have done with better naming. I would have been happy with the term HatEoAS if it had stood for “Hypermedia as the Envelope of Application State” rather than “Hypermedia as the Engine of Application State”. (by Ganesh Prasad)

hypermedia binding – “a solution to the evolving-over-time problem for dist-net apps is to bind clients and servers via a shared understanding of hypermedia controls. IOW, change the binding from first-class domain elements to an abstract expression of those elements; to elements (links and forms) that make “animating” dist-net apps possible.” (by Mike Amundsen)

Discussion groups

Which URIs are bookmarkable? – Very interesting thread on the “theory” behind bookmarking links. “In general, I am trying to answer the question:What are the indicators in media type (and link relation) specifications that tell the user agent implementor what URIs in responses of the media type in question can be considered bookmarkable?”

Reviews of draft-freed-media-type-regs-01 needed – Roy’s thoughts on media type registration process. “We should be *encouraging* vendors to ship with vendor-neutral short-namedtypes regardless of whether they have been registered yet or not, and thenwe should be *encouraging* the public to register any names that they haveseen in deployed software.”

Using URI templates in XHTML– Interesting thread on URI templates and hypermedia controls. “I’d like to use URI template as hypermedia control in XHTML, as a (richer) alternative to my existing forms. What do you think is the best way to do so ? Specifically, how would you represent an URI template in XHTML (given it must be used as a hypermedia control for programatic clients)?”

absolute or relative URLs in links? – “Is there a consensus?An absolute URL is, I guess, easier to consume by a client, whereas a relative link is also going to need some sort of (equivalent to HTML)BASE tag so that the client can build the URL to hit.”

Denormalizing Data In To Collection Resources? – “Is there any good research trading off the chattiness, cachability,latency and redundancy of denormalized data in RESTful collection resources? Are there good rules of thumb to apply here. It’s temptingto say do the N hundred HTTP requests and come back when you can showit’s a problem, but that doesn’t go down well…”


W3C Workshop on Data and Services Integration – Papers from the W3C workshop held on October 20-21 2011 in Bedford, MA, USA.

Interesting tweets

@mikekelly85 – “HTTP error responses aren’t reps of a resource’s state, they’re reps of a failure state produced by an intermediary mechanism”

@dret – “search is not a function or a property of a single resource, it’s a capability available for a collection & may be independent of it. #REST

@AndrewWahbe – “Think of a hypermedia type as a client-defined interface that services can implement to plug into the client”

@mamund – “RT @dret: “once you hit a resource where the representation signals success, that test has been successful.” express as assert, right? #REST

@kidehen – “Data is the New Electricity with Hyperlinks (#URIs) as the conduction mechanism :-) #LinkedData #GartnerSym

@mamund – “media types can be used to express shared understanding of problem domain(s) in an implementation-agnostic format. #HTTP #REST #Hypermedia

@distobj – “Pro tip; when writing HTTP/JSON apps, throw in a crude-but-complete HTML repr to keep you honest wrt hypermedia #REST

@dret – “any non-trivial testing of #REST services needs “random link exploration” and some domain knowledge of “test space boundaries.” what else?”

@mamund – “RT @amirrajan: “still question the need for “restful” uris when you have hypermedia” i agree: startingURI(s)+HM = minimal URI rules (cont)”

@dret – “@mamund goal-driven state machine based clients doing some validation and aggregation along the way. it’s a huge research opportunity!”

@dret – “there’s #HTTP, there’s #WebDAV on top, and now there’s #CalDAV and #CardDAV. do we really need a specific protocol for each application?”

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: