This is Volume 41 of This week in REST, for November 17 2011 – December 29 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! And…

… HAPPY NEW YEAR! :)

Around the Web

HTTP status cats - (Lol)cat images for different HTTP status codes. And the follow-up: HTTP status dogs.

Evolution of the Web – “The Web is not finished. Evolution is necessary to adapt to new requirements, add new features and fix problems in response to changes in circumstances, applications, and user needs. How does evolution happen in a way that does not break it? Traditional means of evolution of formally defined languages, protocols, and standards do not fit well with the way in which the Web evolves. Unmanaged evolution results in diminishing the interoperability of components, a cost to all which must be weighed against the benefits of evolution. There are a number of issues that need to be addressed to help achieve the goal of global interoperability in an evolving world. This document analyzes some of the issues and makes recommendations for best practice.” (by Larry Masinter)

Understanding URI Hosting Practice as Support for Documentation Discovery – “This document defines version 1.0 of the URI Documentation Discovery protocol, or “UDDP 1.0″. The protocol is a way to ask the agent that controls resolution behavior for a URI what it thinks the URI means or should mean.” (by Jonathan A. Rees)

WebSockets versus REST… fight! – ” On 8th December 2011, a little known (but growing in awareness) standard called “WebSockets” was upgraded to W3C Candidate Recommendation status. … After reading up about the standard in detail and absorbing the various online discussion around it, it is becoming increasingly clear to me that this standard is going to steal a large chunk of mind share from RESTful web services. What I mean is that there will come a stage in product development where somebody will have to ask the question: Right guys, shall we use WebSockets or REST for this project?” (by Nathan Evans)

SPDY: What I Like About You. – “tl;dr; Faster is all well and good (and I mean that!) but I’m going to make a long argument that SPDY is good for the Internet beyond faster page load times. Compared to HTTP, it is more scalable, plays nicer with other Internet traffic and brings web security forward.” (by Patrick McManus)

Action URIs – “anybody doing non-trivial things with REST sooner or later runs into interactions beyond the simple CRUD (create/read/update/delete) operations. there often are cases where operations might be tied to a specific resource (or mainly to that resource), and then the question is how model this in a RESTful way. a pattern that is seen frequently is the action URI, which is a URI that specifically represents one action on one resource.” (by Erik Wilde)

REST : ‘inverted’ architecture – “history has shown that the HTTP protocol is a very flexible protocol and that not all implementations need to follow the example provided by Fielding in order to meet the needs of users. for example, RPC over HTTP works just fine for many cases; esp. those that do not require system stability on the scale of years/decades.” (by Mike Amundsen)

Write Better Cukes With the Rel Attribute – “The other day, I was working on some Cucumber features for a project, and I discovered a neat technique that helps you to write better Cucumber steps. … When doing research for my book on REST, I’ve been doing a lot of digging into various standards documents. And one of the most important attributes from a REST perspective is one that nobody ever talks about or uses: the rel attribute.”(by Steve Klabnik)

requestb.in – The awesome postbin webapp got upgraded and polished. “RequestBin lets you create a URL that will collect requests made to it, then let you inspect them in a human-friendly way. Use RequestBin to see what your HTTP client is sending or to look at webhook requests.” (by Jeff Lindsay)

Mobile API Design – Thinking Beyond REST – “This article explores the problems of optimising REST APIs for mobile device performance, and suggests a way of allowing clients to request alternate representations.” (by Dan Fairs)

Restfuse 1.0.0 – A Library For Easy REST/HTTP Integration Tests – “EclipseSource has released the first stable version for an open source JUnit extension that automates testing of REST/HTTP services. Restfuse is a set of JUnit annotations that, along with the respective HttpJUnitRunner, offer assertions against the response of an HTTP call. Both synchronous and asynchronous remote calls are supported.” (by Kostis Kapelonis)

Nutshell Definitions – “I try and distil a concept into a single word, or at most a short phrase, in order to understand it. This has been very useful to me in evaluating the merits of technologies and comparing them to others. Call these my trade secrets which I’m now sharing with you :-).OK, so here are some of my definitions of popular terms, each in a nutshell:” (by Ganesh Prasad)

Ruby On REST: Introducing the Representer Pattern – “This post introduces the new Roar gem, a framework-agnostic RESTframework for Ruby that puts focus on object-oriented RESTdocuments.” (by Nick Sutterer)

Media Types in RESTful HTTP – “A topic that comes up again and again in discussions about RESTful design is what kinds of media type to use. I’ve changed my mind about this a few times, often enough so that I believe it makes sense to write a bit about my current thinking on this. (A “media type”, should you happen to wonder what I’m talking about, is a specific format with a well-defined name, in this context represented in the form of a media type identifier such as application/xml or text/html or application/json.” (by Stefan Tilkov)

Best Practices for HTTP API evolvability – “One thing we know is that these APIs will change, so what can we do at a technical level to deal with these changes as they occur? The main moving parts of a HTTP API are * The generic semantics of methods used in the API, including exceptional conditions and other metadata * The generic semantics of media types used in the API, including any and all schema information * The set of URIs that make up the API, including specific semantics each generic method and generic media types used in the API. These parts move at different rates.” (by Benjamin Carlyle)

JSON Linking with HAL – “We need a media type (the HTML of machines), not another XLink. We need a general purpose media type, which extends JSON, that can be used as a standard way to represent a resource and its relations to other resources on the Web.It’s very important, particularly because we are talking about JSON, that this media type be simple in its design.” (by Mike Kelly)

Announcing ql.io – “ql.io is a declarative, evented, data-retrieval and aggregation gateway for HTTP APIs. Simply put, this is our answer to the pain points that I recently described in my APIs are a Pain post.” (by Subbu Allamaraju)

Introduction | The Object Network – “It’s interesting to compare the current growth of Web APIs with the early growth of the Web itself. To save you jumping those links: the Web dramatically beats the APIs. I believe that the most likely cause of such relatively slow growth (in what should be a booming ecosystem) is that each API forms a closed silo and cannot benefit from any network effects. Every API is different and there are no links between them. There usually aren’t any links within a silo. You can’t even use a given API without first consulting the documentation. The Object Network is designed to fix this, with linked-up JSON in common formats. This will allow easier mashing, sharing and cacheing of data and allow client code to be shared and reused.” (by Duncan Cragg)

Discussion groups

Oh, please no. JSON is a data format. If you want a hypertext format there’s HTML for that. – A really long and interesting discussion concerning links in JSON.

Rails 3.2 and PATCH – another long and interesting thread on PUT and PATCH semantics.

Restoring PUT and DELETE – “Can we revisit the decision to remove the PUT and DELETE verbs from HTML5.”

Discussion points on HTTP “evolutions” – “HTTP is now used more and more to deliver data to web application, usuallyin small chunks. One result is that people wants to optimize the use ofHTTP, or HTTP itself (by modifying it, or modifying the underlyingtransport) to reduce latency, bandwidth usage etc…Another aspect is that Web content is more and more delivered toauthenticated users, meaning that the authentication part and the contentretrieval may be subject to snooping or worse, impersonation. Firesheep is a good example of a simple way to doreplay attacks when authentication is done in the clear through cookies. Areaction to that is to use https which has its own set of issues.”

Negotiated private cache storage allocation – “Is anyone aware of any proposals that extend HTTP to allow servers andclients to negotiate client-side storage allocation for client-side(private) caches?Basically, I’m looking for a way for a server to indicate how muchstorage should be allocated for caching responses from a particulardomain name, and possibly also for the client to be able to indicatehow much allocation was actually possible.”

weighting and boundaries of evolvability and loose coupling? – “one major aspect of using hypermedia is loose coupling and evolvability. butwhere are the boundaries? which server-side changes may/may not affecthypermedia-aware clients?for example: as a human user, i can easely adapt to a change in a web shopsystem, e.g. when the order procedure include suddenly an additional step likeproviding an optional voucher code.”

service “definition” techniques - ”Is anyone using something like WADL for service definition documentation? We’re(hopefully) going to have a collection of many services in multiple domains andwe’ll be expected to have a standard ‘template’ for defining/documenting aservice. I’m curious if anyone in an “enterprise” situation has run into thatand has any advice.”

Using # in link relations to distinct links of the same relationship – “Several times i came to the question, wheter to specify a relation with somekind of index to distinct links of the same relationship type. examples:

GET /products/canon

<category name=”canon” …><link href=”…” rel=”http://example.com/item#1&#8243; …/><link href=”…” rel=”http://example.com/item#2&#8243; …/><link href=”…” rel=”http://example.com/item#3&#8243; …/></category>”

Noob question – “I have a list of tasks resource (PATH: /tasks). What rules of REST will break ifI made /tasks return different result for different sign in users (It could be/users/1/tasks)? What is the disadvantage of that? Thanks.”

The “new media types are evil” meme – “I’ll give a few of thereasons using a generic media type is the better option… Is someone able to put together a similar list for the “new mediatypes are awesome” meme?”

REST = no interoperability! – “Allow me to try a debate that is a bit more opiniated than my normal posts:REST will never get any break-through in M2M scenarios due to it’s completelack of interoperability! [ducking for cover]“

REST is not about domain models – “If “REST is not about domain models” (as Glenn Block states it here:http://tech.groups.yahoo.com/group/rest-discuss/message/18117) how are wethen going to solve machine-to-machine scenarious where it is all aboutspecific domains? By not using REST? I know this is beating an old horse,but I still have issues with the idea of ignoring the domain of a system.”

Less REST, more Hypermedia! – “I think, it is time to push forward terms like “hypermedia service/API” or”hypermedia-aware client”. Instead of saying “hey i have a RESTful API”, tellthe people “i have a hypermedia API!”.”

Events and books

WSREST 2012 – WSREST is on again next year, find the CFP here.

ICSOC 2011 – This year’s ICSOC (International Conference on Service Oriented Computing) was held in Paphos, Cyprus. Have a look at the many interesting papers in the main program and workshops.

Building Hypermedia APIs with HTML5 and Node – a new book by Mike Amundsen “With this concise book, you’ll learn the art of building hypermedia APIs that don’t simply run on the Web, but that actually exist in the Web. You’ll start with the general principles and technologies behind this architectural approach, and then dive hands-on into three fully-functional API examples.”

Interesting tweets

@mamund – “breaking changes on the WWW is an anti-pattern; when the lifetime of a “API” for the WWW is counted in months (not years) that’s a #fail.”

@algermissen – “REST frameworks that hide too many HTTP details tend to really get in your way in the long run :-(“

@mamund – “#hypermedia challenge: what if you were not allowed to put any URIs in your client code? could you still write a fully-functional app?”

@dret – “mapping server-side #XML directly to URIs leads to (a) excessive granularity, (b) namespace problems, (c) API instability, and (d) insanity.”

@dret – “or more generally speaking: link relationship types should not make any assumptions about the media types on both ends of the link.”

@dret – “another link relationship registry question: wouldn’t it be very useful to know when two relationship types are the inverse of each other?”

@darrel_miller – “Different media types are like different vehicles on the road. Use the right one for for the right job.”

@dret – “apart from priority, in-representation links, protocol-level links, and external link overlays should all be treated equally. #REST”

@mikekelly85 – “Fellow devs; please stop creating custom media types for your web APIs. You don’t extend HTML to build a web app, why do it with an API?”

@mamund – “creating stand-alone app requires mapping problem domain to src code. creating WWW app requires mapping problem domain to msgs. #Hypermedia“

@joehewitt – “Maybe the biggest threat to the web is JSON APIs, the lingua franca of native apps, which offer no hyperlinking and no standard semantics.”

@mikekelly85 - ”Atom(pub) failed because it forces you to model resources as collections & items, instead of other way round i.e. cols/items as resources”