This Week in #REST – Volume 43 (Mar 7 2012 – Apr 3 2012)

This is Volume 43 of This week in REST, for March 7 2012 – April 3 2012. 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

What’s next for HTTP? – See the links in this post for presentations about the future of HTTP/1.1 and /2.0 (WAKA, SPDY, etc). “We had two great meetings of the HTTPbis Working Group in Paris this week — one to start wrapping up our work on HTTP/1.1, and another to launch some exciting new work on HTTP/2.0.” (by Mark Nottingham)

PubSubHubbub Core 0.4 Working Draft – Julien Genestoux has started revising the PSHB spec based on feedback. See forum discussion thread here.

Loading Data From The API – How Much Is Too Much? – “I’m really liking what’s coming together with this Hypermedia-ish API. So many ideas and approaches are starting to come into focus. Like this one: how much structured data do I pass on the initial load of the API?” (by Rob Conery)

RESTful services as intelligent websites – “In this post I’ll try to address a few important aspects of RESTful services, considering them as intelligent websites. We might need more formal specifications in some cases, but this is hopefully a good start.” (by Bertrand Delacrétaz)

Test Your RESTful API With YQL – “When saying earlier that building an API can be complex, I rather meant that it is difficult to get it “right”. So how can you find out if you got it right or not? In this article I am proposing to use YQL as a tool to assess the quality of your RESTful API, in terms of following best practices and standards.” (by Sebastian Spier)

Automated Documentation for REST APIs – “From time to time, people who have a REST API ask me about automated documentation. There’s no one right answer, so I’ve been meaning for ages to write an article about what the options are.” (by Peter Gruenbaum)

Rest test test – “A native in-browser tool for testing REST/CORS services.” (by Jeroen Ooms)

API jobs – Web engineering jobs aggregation page that focuses only on jobs concerning APIs.

URI templates – URI templates is now an RFC (standards track).

The ‘profile’ Link Relation Type – “This specification defines the ‘profile’ link relation type that allows resource representations to indicate that they are following one or more profiles. A profile is defined to not alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics that are associated with the resource in addition to those defined by the media type and possibly other mechanisms.”

PATCHing AtomPub – “one of the advantages of PATCH is that updates can use any kind of diff format that is deemed appropriate for the application, and thus (in case or larger resources, for examples) it may be desirable to use the general patterns established by AtomPub, but to allow updates by PATCH, maybe in addition to PUT, or as the only allowed method for updates. but what would it take to PATCH-enable AtomPub? there are (at least) three possible answers, and i am curious to see whether there is some community consensus for the best one.” (by Erik Wilde)

REST Design Philosophies – “instead of best practices everybody agrees on REST has a number of distinct schools of thought or design philosophies; neither inherently good nor bad, neither obviously right nor wrong; each with its champions and detractors.I’ll attempt to describe four of these design philosophies without claiming any authority in the matter. Others would likely name and describe them differently. I decided to draw quick sketches instead of painting full portraits, capturing the distinctive features and worrying less about getting every detail right.” (by Ferenc Mihaly)

HATEOAS Openstack Keystone - “Of all the principals of REST, perhaps the most overlooked it Hypermedia as the Engine of Application State, or HATEOAS. This term tries to encapsulate several concepts together, but the primary is the principal of discoverability.” (by Adam Young)

REST and the Art of Protocol Design – “RESTful protocol design is a topic more appropriate for a book than a blog post. Despite the catchy title my goal is very modest. I would like to show you that even limited protocol design knowledge can help you understand the essence of REST and the reasoning behind many of its best practices.” (by Ferenc Mihaly)

REST Layers and REST Applications – “in an attempt to better understand what and why people are trying to accomplish when they try to describe REST, here is a first approach to more cleanly layer the issues, see what’s already around, and try to figure out what value could provided by some format/technology for each layer. we are actively working in this area because we simply need something that will allow service providers to describe (and by that we mostly mean document) their services. our platform allow customers to define and expose REST services, and when they do this and want to point, for example, external partners at these services asking them to develop clients, instructing them to tell your external partners to follow their nose just doesn’t quite cut it.” (by Erik Wilde)

You can’t achieve REST without client and server participation – “Recently I have been having a bunch of discussions around REST and whether or not the client participates in the RESTfulness of a system. Until now I’ve been saying that REST is confined to the server. I now realize that was wrong. Having a server which adheres to the constraints without clients that obey the same constraints will NOT yield the full benefits of REST.” (by Glenn Block)

Hypermedia Client Maturity Model – “One area that has not had as much attention paid to it is that of the client. Although it is necessary for a service to be RESTful in order to build a system that exhibits RESTful characteristics, it is not sufficient. The client needs to behave RESTfully or the coupling that the server tried to avoid will be re-introduced.” (by Darrel Miller)

Upgrading WebHooks To Be More Useful – “We should upgrade WebHooks so that they can be created by submitting a form/template of the callback request to be generated. This will allow users to connect APIs together arbitrarily without having to wait for providers to do the work to make it happen.” (by Mike Kelly)

http://httpstatus.es/  – “Database of HTTP status codes with their IETF and Wikipedia descriptions.”

Discussion groups

Does the client contribute to the RESTfulness of an application? – Longish, but very interesting discussion on whether client components contribute to the RESTfulness of a hypermedia system.

Changing the httpRange-14 resolution – There has been a number of discussion on the W3C TAG list about amending the httpRange-14 issue resolution.

The HTTP vs SPDY debate – There’s also been a number of discussions on the IETF HTTP mailing list about HTTP 2.0 and SPDY’s role in it.

Interesting tweets

@savasp – “If one wishes to change the Web, one first needs to understand it! I happen to believe that the Web-as-a-platform is absolutely fine as is!”

@DanaDanger – “HTTP response codes for dummies. 50x: we fucked up. 40x: you fucked up. 30x: ask that dude over there. 20x: cool.”

@dret – “#REST design is about resources and links and about these only; #URI patterns are 100% a deployment issue and are not part of the design.”

@dret – “new #REST rule: no, you cannot play with your URIs until you have designed all of your media and link relation types.”

@mamund – “wonder if anyone has done the work Fielding describes here: http://g.mamund.com/zebnj there might be thesis/dissertation material. #REST #Web“

@fuzzyBSc – “#REST and #SOA integration differ in that SOA creates a service to be the integration point while REST creates a media type to be that point”

@dret – “I love the smell of RPC in the morning.”

@dret – “nobody says “they are calling a web page” or “calling a form API”; why do many “#REST” services assume it makes more sense outside of HTML?”

@dret – “in the same sense as there is the “dark web”, there are “dark web services”, which are all those ones which are not properly linked. #REST”

@dret – “do you design your web site in terms of what users can enter in the address bar? then why should it makes sense for web services? #REST”

@dret – “the three pillars of #REST: data model (what to expect), processing model (how to process), operational model (where to go and why and how)”

This Week in #REST – Volume 42 (Dec 30 2011 – Mar 6 2012)

This is Volume 42 of This week in REST, for December 30 2011 – March 6 2012. 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 I’m sorry for not blogging more often – I’ve been very busy over the last few months.

Around the Web

Fitful Sleep – A Savage Chickens cartoon about the 404 status code.

Civilisational HTTP Error Codes – “To be truly useful, HTTP error codes need to take into account possible future issues.”

RFC for the 7XX Range of HTTP Status codes – Developer Errors – “There are many ways for a developer to screw up their implementation, but no code to share the nature of the error with the end user.We humbly suggest the following status codes are included in the HTTP spec in the 7XX range.”

STOP SOAP

When “identification” and “representation” fight, who wins? – “Let’s now enter the fantasy world where “resource”, “identification”, and “representation of” have meanings consonant with what is found in the Web architecture documents RFC 3986, the HTTPbis draft (I’m looking at version 18), and AWWW. To make any sense of these documents the words have to be assumed to have something close to their ordinary language meanings (which are rather squishy), since they are otherwise effectively undefined.” (by Jonathan A Rees)

Entities and actions – “hypermedia designs focus on the actions taking place in the problem domain. things like “get a list of customers sorted by date” and “allow users to filter the order list by sales region” and “allow selected users to add new customers”, etc. are all actions. when implementing a system using these actions as the centerpiece, hypermedia designs select the appropriate affordances (within the selected media type) and map those affordances to the identified actions.” (by Mike Amundsen)

Building a Modern Web Stack for the Real-time Web – “The new protocols are here, but the supporting “back office” architecture requires a serious update: SSL is becoming the default, streaming is no longer an option, and long-lived persistent connections are in. SPDY is gaining momentum, and I have no doubts that in the not so distant future it will be an IETF approved protocol. Similarly, ØMQ is not the only alternative for internal routing, but it is definitely one that has been gaining momentum. Fast HTTP parsing and routing is simply not enough to support the modern web use cases. Likewise, punching “TCP holes” in our infrastructure is not a viable long-term solution – in 2012 we should be asking for more. Yes, I’m looking at you Varnish, Nginx, Apache and friends.” (by Ilya Grigorik)

S: A Scripting Language for High-Performance RESTful WebServices – a presentation for the paper by the same name, from the 17th ACM SIGPLAN Symposium on Principles and Practice.

Building Hypermedia Web APIs – “Many of the media types we use nowadays for building Web API’s such as JSON or XML don’t have a built-in concept for representing hypermedia links as HTML does with links and forms. You can leverage those media types by defining a way to express hypermedia, but again, it requires client to understand how the hypermedia semantics are defined on top of those. Other media types like XHtml or ATOM already support some of the hypermedia concepts like links or forms.” (by Pablo M. Cibraro)

WS-* vs REST for the Internet of Things – “I wanted to discuss this choice and base it on data, first looking at quantitative results (e.g., performances of REST vs WS-*) but then also getting some qualitative data: does REST really makes it easier to build upon smart things? WS-* and REST have previously been compared with respect to performance and features, but no work has been done to elicit the developers’ preferences and programming experiences in an Internet of Things context…”

JSON, HTTP and data links – “… I sensed that the community at large is ready for the next aspect of the Web. A scalable, machine-targeted way to realise a global dataspace. And it’s happening as we speak.Take JSON and HTTP (some use REST for marketing purposes) and add the capability of following (typed) links that lead you to more data (context, definitions, related stuff, whatever).And here are the three current contenders in this space.” (by Michael Hausenblas)

HTTP at a glance – “Many web developers using HTTP don’t think about the protocol itself. This site should provide a basic understanding of HTTP 1.1 and ease the development of web applications that use HTTP.This “HTTP explanation” is an incomplete, simplified, human-readable summary of the full specification.”

Object Network -mapping the web – (talk) “Duncan Cragg will give a talk for the London Android User Group on Object Network. Instead of writing a whole new, dedicated HTTP API to your site, publish your data using common JSON object formats, and link your data up, both within your own sites and to other sites. Become part of a global Object Network! See http://the-object.net” (by Duncan Cragg)

REST vs. Websockets, Oh My – “There is an entirely absurd discussion going on about “REST vs. Websockets”, predictably claiming that in the long term, REST will be succeeded by Websockets. This is stupid on many levels. I’ll try to be brief” (by Stefan Tilkov)

Additional HTTP Status Codes – “This document specifies additional HyperText Transfer Protocol (HTTP)status codes for a variety of common situations.” (IETF document, by Mark Nottingham)

HTTP is not a transport protocol, HTTP is not RPC – “This has deep implications in your API design. Once you accept that the thing that you are exposing is an HTTP resource which clients interact with via the uniform interface and not a class with standard OOP methods, you design them differently. Your APIs become a gateway where HTTP concerns are addressed and then work is delegated off to the business domain rather than being part of the business domain.” (by Glenn Block)

Resource Profiles – “in our work on RESTful services, we have repeatedly run into the situation where we want to have a runtime mechanism how a resource can represent the fact that it follows additional constraints and/or rules. creating media types at runtime is not such a great idea, and it would also not allow us to represent the fact that a resource is still using a representation based on some media type, but also can be treated according to additional constraints and/or rules. a profile mechanism would be a good way of doing this, and thus we would like it to become a recognized link relation type.” (by Erik Wilde)

Hypermedia Analysis – “This project tries to establish a baseline concerning HATEOAS deployment on the Web, that is, collecting a statistically relevant sample of representations offered by so called RESTful APIs and determine to what degree they ‘contain hypermedia’. We will do this in two phases:First, we will use the Programmable Web API to determine target APIs and retrieve representative samples of representations from those APIs in an automated fashion.Second, we will, manually, evaluate the repository of API representations and determine how to measure the ‘degree of hypermedia’ used.”

ROCA Resource-oriented Client Architecture – A collection of simple recommendations for decent Web application frontends – “ROCA is an attempt to define a set of recommendations – independent of any particular framework, programming language, or tooling – that embodies the principles of what we consider to be good web application architecture. Its purpose is to serve as a reference, one that can be implemented as is or be compared to other approaches to highlight diverging design decisions.”

Someone Save Us From REST – “REST is a fascinating and illuminating set of ideas and, as it turns out, is a handy guideline for effectively preparing an API. As it turns out – digging deep into what you think REST means runs the perils of digging deep into any religious philosophy: adherence turns into devotion.I like REST like I like any [Religious Doctrine]. I dislike the people who drop Fielding Passages in some apostolic attempt to save my non-RESTful soul. My relationship with REST is a personal one and, frankly, I like to think REST guides me in my application development walk in the way Fielding intended for me, and my web app.” (by Rob Conery)

POST-PUT-PATCH illustrated – “the announcement that Rails is adding support for PATCH has caused some gum-flapping on the Inter-Tubes and this all came up in a recent convo w/ some of my colleagues today. it turned out most of them don’t have much experience in “talking HTTP” but know T-SQL really well. so i decided to illustrate the differences between HTTP’s POST, PUT, and PATCH methods using simple T-SQL examples.” (by Mike Amundsen)

REST will stay – you can wash your SOAP away – “REST web services will stay. It is a bad thing to predict future of technology. But I am ready to bet on this one. REST will stay. It will stay because of multiple reasons, and today I am going to give you mine.” (by Samik Chakraborty)

Afforded agents – “data needs to be “afforded” – we need to see not just the “what” in a message, but also the “how.” i appreciate the work the Semantic Web community has done in order to get folks thinking about the idea of messages having “meaning”; that’s great. unfortunately, the same community has not done well in getting folks thinking about the idea of messages having “affordance” – use-ability built right into the data itself.” (by Mike Amundsen)

ql.io - Consuming HTTP at Scale – presentation on ql.io from the Node Summit , Jan 24, 2012

Nobody Understands REST or HTTP – “The more that I’ve learned about web development, the more that I’ve come to appreciate the thoroughness and thoughtfulness of the authors of the HTTP RFC and Roy Fielding’s dissertation. It seems like the answers to most problems come down to “There’s a section of the spec for that.” Now, obviously, they’re not infallible, and I’m not saying that there’s zero room for improvement. But it really disappoints me when people don’t understand the way that a given issue is supposed to be solved, and so they make up a partial solution that solves their given case but doesn’t jive well with the way that everything else works. There are valid criticisms of the specs, but they have to come from an informed place about what the spec says in the first place.Let’s talk about a few cases where either REST or HTTP (which is clearly RESTful in its design) solves a common web development problem.” (by Steve Klabnik)

Discussion groups

Rechartering HTTPbis – epic thread on HTTP 2.0 and SPDY “When this effort was started we took great pains to make it clear that we weren’t working on a new version of HTTP, because there wasn’t implementer support to do so and we wanted to focus upon interoperability and security.That’s clearly changed in the intervening time; two major browsers have implemented SPDY, a non-textual serialisation of HTTP’s semantics, and there are now several other implementations as well (full disclosure: including an experimental one in Python by yours truly).I’ve been talking to a number of folks — including those implementing SPDY, as well as HTTP implementers and the W3C TAG — about this recently. There seems to be broad agreement that the time is ripe to start work on a new version of HTTP in the IETF, and that it should happen in this Working Group.”

Where should I POST to? – “Here are different ideas to create a comment:- “POST on /posts/43″ – According to the definition of POST [1], this should be acceptable under “annotation of existing resources”.- “POST on /posts/43/comments” – According to the definition of POST [1], this should be acceptable under “posting a message […]”The question: which one(s) of the above seem acceptable, which one is “best”?”

Formats with native hypermedia support – “I’m trying to create a list of formats with native hypermedia support (HTTP)that goes beyond just links supporting a GET.. So far my list is quite shortand I can’t believe that that’s all:- HTML (GET/POST/PUT)- Atom & AtomPub (GET/POST/PUT/DELETE)- WSDL (GET/POST/PUT/DELETE)- WADL (GET/POST/PUT/HEAD/DELETE)- Collection+JSON (GET/POST/PUT/DELETE)”

Related resource: Inlined or linked – “It sounds like the related resource may be either linked or inlined – whatever the server decides. I can understand the approach if the media type explicitly says that there should be either a link OR an inlined resource. But when it says there should be an inlined resource and the server decides to return a link to it, then the server is not implementing the media type anymore. And vice versa, when media type says there should be a link, but the server returns an inline target resource.”

Design styles: OO/URIs compared to Media Types – a lengthy discussion about APIs: “I wonder if you (and anyone else on this list) would be wiling to talk about why you favor OO-URI design over message design (or vice-versa, if that’s the case)?Note I am not at all interested in what is “right/wrong” or “what Fielding sez should be done”, etc. I am most interested in the preferences people have and why they have them. This would help me a great deal in some explorations in which I am currently involved.”

either strengthen or retract httpRange-14(a) – “Personally I feel that the (a) clause of the httpRange-14(a)resolution MUST NOT stand as it is. It must be either strengthened orretracted. It is terribly confused, does not solve the problem the resolutionclaims to solve, and has divided the community in verydestructive ways.”

HATEOAS: concise description – “I am trying to get a clear and concise understanding of HATEOAS, and I am by no means an expert WRT REST. Can anyone suggest an equally enlighenting blog/article WRT HATEOAS?”

Introduction | The Object Network – “Let’s presume for a second that this succeeds, what could I then do that couldn’t do today. Or what could I do more easily than I could today?”

Review: http://www.ietf.org/id/draft-mbelshe-httpbis-spdy-00.txt – discussion about the SPDY protocol proposal.

Idempotent partial updates – interesting thread about PUT and PATCH for partial updates. “HTTPbis has amended the semantics of PUT to be unambiguous in its prevention of partial updates. I cannot understand the rationale behind this change, and I have a couple of questions for the group:”

[p3-payload] Media-Type — Two Values, One Cup Anti-Pattern? – “Early media types constrained themselves strictly to describing the format(syntax) of the representation (image/png, application/xml). As time woreon, though, media types sprang up that contained both syntactic & semantictype information (see the application/vnd.openxmlformats-*+xml series foran example). Negative ramifications seem obvious (add json, yaml => m*ntypes, parsing, querying, …); in fact, in other contexts (DB & objectfields), placing two values into a single cup/bucket is such a basicmistake with such obvious drawbacks, it’s rarely even discussed as an issue.Does anyone else see this as a problem?”

Events and books

“APIs: A Strategy Guide - Creating Channels with Application Programming Interfaces” – New book from O’Reilly: “Learn about the rise of APIs and why your business might need one. Understand the roles of asset owners, providers, and developers in the API value chain. Build strategies for designing, implementing, and marketing your product. Devise an effective process for security and user management. Address legal issues, such as rights management and terms of use. Manage traffic and user experience with a reliable operating model. Determine the metrics you need to measure your API’s success” (by Daniel Jacobson, Greg Brail, Dan Woods)

Interesting tweets

@fielding – “@robconery Partial PUT violates the HTTP standard, not REST. Broken hacks should be fixed before deployment, regardless of how it is argued.”

@blowdart – “There’s only one thing as far as I am concerned that HTTP 2.0 can do. FIX THE SPELLING OF REFERRER.”

@serialseb – “Design your media types for extensibility, versioning is not the right change control mechanism at the scale of the web.”

@duncancragg – “My HTTP/2.0 list has just 2 items: asynchronicity and bidirectionality. Which is really just ‘POST requests that look like GET responses’”

@dret – “wondering how much confusion is caused by #REST calling clients “applications”, and many others talking about “application servers”.”

@mamund – “dist-net comms distilled: each request is 1) mutable/immutable? 2) safe/unsafe? 3) idempotent/non-idempotent? 4) navigation/transclusion?”

@dret – “interested in #REST engineering positions at @EMCcorp in Pleasanton, CA? we’re hiring! 2012 summer interns are welcome to apply as well.”

@fielding – “Please don’t argue against principled design on the basis that “real developers” don’t care about design principles. They have no choice.”

@aphethean – “If I had to have a #REST motto, I think I’d like mine to be “resources are cool, so are URIs”"

@kellabyte – “@ICooper +1 HTTP API. REST may not even fit for many probs, nobody is saying everything should be REST. Just don’t mislabel what you built”

@howard_dierking - ”another day, another post describing “RESTful URLs”…sigh…I’m going to have to change all RESTbugs URLs to GUIDs just to make a point”

@dret – “wondering how many document types average media types define. #HTML: 2; #Atom: 2; #AtomPub: 2. does that translate to: usually few? #REST”

@mikekelly85 – “Web intents as a concept is fine, but why not re-use what we already have? i.e. just use <link> and @rel instead of <intent> and @action”

This Week in #REST – Volume 41 (Nov 17 2011 – Dec 29 2011)

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″ …/><link href=”…” rel=”http://example.com/item#2″ …/><link href=”…” rel=”http://example.com/item#3″ …/></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”

This Week in #REST – Volume 40 (Sept 12 2011 – Nov 16 2011)

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 avoided.in 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…”

Events

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?”

This Week in #REST – Volume 39 (Aug 11 2011 – Sept 22 2011)

This is Volume 39 of This week in REST, for August 11 2011 – September 22 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

InfoQ Explores: REST – “This is the first edition of what is expected to become a recurring series on InfoQ. The idea behind this minibook is that a number of InfoQ articles and interviews which deal with a particular topic (in this case, REpresentational State Transfer, or REST) are combined together to provide a detailed exploration suitable for both beginners and advanced practitioners.”

Restful turing machines – “I went to bed a couple of hours ago but every time I started to drift off a mosquito buzzed by. Led to this train of thought – how would you build a Universal Turing Machine with hypertext as the engine of state?” (by Danny Ayers)

Clarifying REST – “The definition of REST lost its way when popular services emerged calling themselves REST which were not. An API like Twitter is ignoring the values of the web and the browser by using HTTP as a transport for RPC (Remote Procedure Call). SOAP services also use HTTP in this way. Instead of doing RPC, HTTP should be used to transfer application state which is what REST is designed for.” (by Kelly Sommers)

Web Oriented Architecture is here to Stay, and Why Microsoft’s new WCF Stack is interesting – “WCF vNext Web Apis is a promising offering from Microsoft, but the key is evolving curry frameworks and tooling on top of the new Web APIs to support address common WOA concerns. WOA is more or less a set of best practices than a well defined methodology, so I’m not sure to what extent this can be abstracted.” (by Anoop Madhusudanan)

Identifying Application State- “This document explores the issues that arise from these new uses of fragment identifiers and attempts to define best practices. We argue that, in many cases, the use of query parameters along with the new HTML5 functionality mentioned above is preferable to fragment identifiers to identify application state.” (by W3C TAG)

Getting Things Done with REST – (video) “Ian Robinson discusses how to implement a hypermedia-driven web application and how to test its workflow giving as example a RESTful web service he built on top of Microsoft’s Web API. ” (by Ian Robinson)

Better Browser Caching – “In discussing my whinge about AppCache offline with a few browser vendory folks, I ending up writing down my longstanding wishlist for making browser caches better. Without further ado, a bunch of blue-sky ideas;” (by Mark Nottingham)

Three levels of abstraction - ”i’ve spent the last year or so focusing on identifying the relationship between the protocol abstraction and the message abstraction. i’ve done this by analyzing various existing media types; developing a set of H-Factors common to all message formats that want to express protocol-level features via hypermedia controls.the next logical step is to analyze existing hypermedia implementations to locate and identify the general principles for expressing domain information within a hypermedia message. ” (by Mike Amundsen)

URI Template – (new version of IETF draft) “A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet.”

When Acronyms Collide: SOA vs. OO – “This article looks at a particular aspect of the current state of enterprise IT: the entangled relationship between the mindset and practices of large-scale Object Oriented application development, and the requirements of Service Oriented Architecture. This relationship has gone wrong and will remain a problem – a costly problem – until it’s put right.” (by Bill Blondeau)

Discussion groups

REST API For Documentation? – “While thinking about documentation for the API we’re working on one ofour team suggested building a REST API to document the REST API. Resources in the documentation API would correspond to media types and contain data on the methods and properties available in those media types. Has anyone seen this done before? How did it work out?”

Conneg based on User-Agent – “human targeted Web sites somtimes (or usually?) adjust the representations they send based on their knowledge about the abilities of the user agents (e.g. IE might get different stuff than FireFox).I think using the UserAgent header to negotiate representation features is a nice solution for non-human targeted situations, too. “

Are URI-Templates really coupling clients and server? – “In different resources on the web, i found different opinions about URI Templating. Some say, they are coupling clients and server (e.g. Erik Wilde). Some propose their usage (e.g. subbu).I dont see any coupling – it is not said, that an URI Template connot changed either over time. As long as the server communicates the templates – like URIs – in resource representations, where is the problem?”

Events

RESTfest 2011 – if you missed this year’s RESTfest, watch the videos on-line here.

ECOWS 2011 – check out the many interesting papers from this year’s European conference on web service and the co-located workshops.

Interesting tweets

@mamund – “RT @dret: @algermissen ”i don’t think app-specific protocols are good way to go.” options: 1)protocol, 2)media-type, 3)URI. i pick 2) #REST“

@dret – “@mamund i prefer to think of it as design patterns of solving common problems with (maybe new) media types and existing methods. #REST“

@dret – “@mamund wrt #WebDAV and #CalDAV: they invent new methods, which are not really something you can easily do by just adding new types. #REST“

This Week in #REST – Volume 38 (Jun 28 2011 – Aug 11 2011)

This is Volume 38 of This week in REST, for June 28 2011 – August 11 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

Building Systems with REST – (video) “Glenn Block presents how developers can build RESTful solutions using Microsoft’s technologies, especially with WCF and .NET. Glenn is a PM on the WCF team working on Microsoft’s future HTTP and REST stack. Prior to WCF he was a PM on the new MEF in .NET 4.0. He has experience both inside and outside Microsoft developing software solutions for ISVs and the enterprise. He has also been active in involving folks from the community in the development of software at Microsoft, including shipping open source products.” (by Glenn Block)

NOTIFY – “Subscribe and pull are pretty handy, but push (especially asynchronous) is just as useful, and often seems to be missing. So where is it at web level?Let’s say I have something named/identified with a URI, like myself, now everytime that’s mentioned anywhere on the web I’d like to know about it (okay not all the time, but it should at least be possible) – insert multiple scenario’s here, conclude that any notification solution needs to be as generalized as possible.So, I simply propose 3 basic things…” (by Nathan Rixham)

Resourceful != RESTful – “Resourceful routing defines paths or routes for objects that the server developer would like to have manipulated with CRUD operations.  The developer can declare an ‘invitation’ to be a resource, and the routes to index all invitations, create a new invitation, download an invitation, update or delete the invitation, are automatically created.  But, problem the first: Resourceful routing uses POST to create a new resource.  PUT is defined as creating a new resource in HTTP, and intermediaries can use that information– but only if PUT is used.  If POST is used, an intermediary can’t tell that a new resources was created. “

my WCF Web API immersion - ”i had the good luck to be able to visit the Microsoft Redmond campus this past week. even better, i got the chance to spend time w/ @gblock and the WCF Web API team. and, in the process, got a serious “immersion” in the WCF Web API library. good stuff!” (by Mike Amundsen)

states: transfers and representations – “over the last several weeks, i’ve been working on a number of hypermedia designs. some of these are for clients’ production implementations but many of them are just explorations of the design patterns and constraints; ways to learn how to effectively and efficiently express a problem domain within a hypermedia type design.it’s been a very interesting experience!what follows are my notes and observations about an ongoing process of discovery related to designing and implementing hypermedia-driven solutions. “ (by Mike Amundsen)

unREST - “So, jdubray at Carnets de bord has thrown down the gauntlet, I guess. He proposes “unREST”. What is unREST? It’s, umm, not REST. Simply put, it’s RPC. Pretty bold proposition, don’t you think?Here’s to hoping that unREST sweeps the internet so that the Restafarians can focus on working out the details of trying to apply REST as given rather than cleaning up everyone’s misconception that REST is using GET over HTTP for RPC.” (by Will Hartung)

How I Became a REST “Convert” – “Much of the criticism of REST comes not from the interaction approach, but rather from the use of HTTP. Roy Fielding, the progenitor of REST, states in his dissertation that REST was initially described in the context of HTTP, but is not limited to that protocol. He states that REST is an architectural style, not an implementation, and that the Web and the use of the HTTP protocol happens to be designed under such style. I chose to implement REST using eXtensible Messaging and Presence Protocol (XMPP) as a way of doing distributed, asynchronous messaging styles of REST-based Service interaction. XMPP, also known as the Jabber Protocol, has already proven itself as a widely-used, highly-scalable messaging protocol for secure and distributed near-realtime messaging protocol. XMPP-based software is deployed widely across the Internet, and forms the basis of many high-scale messaging systems, including those used by Facebook and Google.” (by Ronald Schmelzer)

REST in the design, use, and documentation of Web APIs – (video) ““If it is on the web, HTTP is the API”“REST help us understand and take advantage of that”REST: Representational State Transfer” (by Peter Keane)

What Do URIs Mean Anyway? - ”If you’ve hung around in linked data circles for any amount of time, you’ll probably have come across the httpRange-14 issue. This was an issue placed before the W3C TAG years and years ago which has become a permathread on semantic web and linked data mailing lists. The basic question (or my interpretation of it) is:Given that URIs can sometimes be used to name things that aren’t on the web (eg the novel Moby Dick) and sometimes things that are (eg the Wikipedia page about Moby Dick), how can you tell, for a given URI, how it’s being used so that you can work out what a statement (say, about its author) means?” (by Jeni Tennison)

Some People Understand REST and HTTP – “As it turns out, there are two companies that you’ve probably heard of who have APIs that are much more RESTful than many others: Twillio and GitHub. Let’s take a look at GitHub first.” (by Steve Klabnik)

JSON, data and the REST - ”From its humble beginning some 10 years ago, JSON is now the light-weight data lingua franca. From the nine Web APIs I had a look at recently in the REST: From Research to Practice book, seven offered their data in JSON. These days it is possible to access and process JSON data from virtually any programming language – check out the list at json.org if you doubt that.” (by Michael Hausenblas)

Identifying Application State – new version of the W3C TAG proposed finding”As the Web has evolved from a Web of documents to a Web of applications, the use of the hash sign, #, in URIs has evolved correspondingly. Originally introduced as a static “fragment identifier” to identify locations in a document, it is now being used in many more complex ways, for example, by SVG and PDF to select from and render documents and as arguments to Web applications that are interpreted by JavaScript. Fragment identifiers are used to provide several different kinds of parameters to the client-side application, such as the actual URI of a video to be played to a video player, or the position and zoom to a map. Unlike query parameters preceded by ?, the characters in the URI bar after the # can be changed without causing the page to be reloaded. Applications and toolkits using fragment identifiers in this way often go to some effort to maintain a history and make sure the back button works as expected. Accessibility and search can, however, be compromised, because without running JavaScript, the URI has no meaning. Such uses of the “fragment identifier” have interesting and different properties, and the usage differs from the way it is described in existing specifications. Recently added functionality in [HTML5] (history.pushState() and history.replaceState()) allows browser history to be changed without causing a page reload thereby providing an alternative to the use of fragment identifiers to identify application state. This document explores the issues that arise from these new uses of fragment identifiers and attempts to define best practices. We argue that, in many cases, the use of query parameters along with the new HTML5 functionality mentioned above is preferable to fragment identifiers to identify application state.” (by T.V. Raman, Ashok Malhotra; W3C TAG)

Collection+JSON – Hypermedia Type – “Collection+JSON is a JSON-based read/write hypermedia-type designed to support management and querying of simple collections. It is similar to the The Atom Syndication Format (RFC4287) and the The Atom Publishing Protocol (RFC5023) . However, Collection+JSON defines both the format and the semantics in a single media type. It also includes support for Query Templates and expanded write support through the use of a Write Template.” (by Mike Amundsen)

Irreconcilable differences – “The ongoing battle for future control over HTML is dominated not only by the usual forces (“whose technology wins?”) but also some very polarized views of what standards are, what they should be, how standards should work and so forth. The debate over these prinicples has really slowed down the development of web standards. Many of these issues were also presented at the November 2010 W3C Technical Plenary in the “HTML Next” session.I’ve written down some of these polarized viewpoints, as an extreme position and a counterposition.” (by Larry Masinter)

Hypermedia APIs – (video) “RESTful web services are one of our core design patterns. Roy Fielding’s thesis identifies four major constraints that identify a RESTful architecture (statelessness, resource-orientation, uniform interface, hypermedia-driven application state). Many “RESTful” APIs only get 3 out of 4 of these; we’ve begun experimenting with using XHTML as a media type for our APIs (instead of the more traditional JSON or Atom types), and this provides a lot of power in terms of scalability and loose coupling between client and server. I can go over these concepts and perhaps even do some coding-on-the-fly to demonstrate some of these client and server concepts.” (by Jon Moore)

Events

IEEE Internet Computing special issue on Programmatic Interfaces for Web Applications - “Although they can take advantage of already existing Web architecture, many APIs that claim to be RESTful actually fail to do so. They overload the meaning of HTTP methods, ignore standard response codes, or do not well support hypermedia to represent relationships among application states. Moreover, developing a programmatic Web interface requires a tight integration with already existing back-end applications and infrastructures, and sometimes requires a new, highly dependable back-end technology. This special issue seeks original articles on topics related to emerging technologies and best development practices that underpin any modern programmatic Web interface. Sample topics include: best practices, patterns, and anti-patterns of a programmatic Web interface design; benchmarking and evaluation of programmatic Web interface scalability and performance in large-scale Web applications; comparisons and empirical evaluation of various styles, protocols, and descriptions for programmatic Web interfaces; reports and lessons learned from developing programmatic Web interfaces for various application domains and sectors; and end-to-end engineering of programmatic Web interfaces and their integration with existing back-end applications requiring the development of novel dependable and scalable technology frameworks.”

RESTFest is a week away - “wow, only one week before the start of RESTFest 2011! there are still some tickets to this ‘smallish’ event. at least one sponsor (Twilio) is offering ‘scholarship’ tickets to worthy individuals, too.” + more info on all the cool events happening on RESTFest 2011. (by Mike Amundsen)

Discussion groups

Comments solicited: “Providing and discovering definitions of URIs” – (W3C TAG mailing list) “As most of you know, the 9-year-old “httpRange-14″ turf war is anannoyance and embarrassment in efforts to develop RDF, linked data,the Semantic Web, and Web architecture.As a step toward getting closure I’ve prepared a document (withthe help of the TAG and the AWWSW task group):  http://www.w3.org/2001/tag/awwsw/issue57/20110625/which attempts to record the variety of approaches that have beenoffered.”

Media type derivation: standardize the + semantics? – (REST discussion group) “Due to previous posts [1] i was asking myself, if it would make sense tostandarize the usage of the + sign in media type indications.I think the benfit would be, that a more specific media type like “application/odata+atom+xml” (which is currently not existing) could be at leastinterpret as “application/atom+xml” (which is currently the media type of anodata resource [2]).”

Is there (a need for) a text/form+html media type? - (REST discussion group) ”In some posts here it is mentioned, one can use simple html forms for providinga decoupled POST/PUT mechanismen. (and thus also avoiding communicatingUriTemplates)I was wondering, if a there is a specific media type for that? Ye, sure one canuse just text/html. But to support better visibility, i could imagine a mediatype text/form+html, that would better communicate the intend…Am i missing something? Is there related work?”

REST and HATEOAS in the context of native applications? - (REST discussion group) “What I really can’t wrap my head around is how, technically, have HATEOAS in anative application? I mean, when building a native application, I have tablesto display lists, buttons to do some things, etc. My understanding is that allthose should be displayed based on the data (hypermedia) received from theserver. Is that right?”

inverse of Content-Location - (REST discussion group) ”To indicate which representation of a resource was sent, the server can use theContent-Location header.E.g., if a client wants an HTML version in Spanish of /news/40, the server sendsthis and addsContent-Location: /news/40.es.htmlBut how can we get to the original, unnegotiated URI from /news/40.es.html?”

Interesting tweets

—

@mamund – “A good #Hypermedia design does not constrain a client implementor’s ability to determine how responses are rendered. #HTTP #REST“

@darrel_miller – “This http://t.co/iIorgIp makes my cry little tears of hypermedia joy.”

@WoT2011 – “#wot2011 proceedings now available in the #ACM digital library #ICPS series!http://portal.acm.org/citation.cfm?id=1993966“

@mamund – “Web Intents <- i love the smell of hypermedia in morning; it smells like.. Victory! #HTTP #Hypermedia #LOD -http://j.mp/nT2bgv“

This Week in #REST – Volume 37 (Jun 1 2011 – Jun 27 2011)

This is Volume 37 of This week in REST, for June 1 2011 – June 27 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

designing a RESTBucks media-type - ”for this blog post, i’ve commandeered the RESTBucks examples from REST in Practice in order to illustrate a simple methodology for expressing application domain details as hypermedia types in a way that works for HTTP and the Web. keep in mind this is my own interpretation of the RESTbucks example and is not meant to indicate the endorsement or approval of the authors of REST in Practice.the material that follows is based on content from a new book i am working on entitled “Building Hypermedia APIs with HTML5 and Node” that will be released later this year.” (by Mike Amundsen)

W3C TAG meeting 6-8 June 2011 in Cambridge, MA, USA – Agenda and minutes from the latest W3C TAG meeting + comments from Jeni Tennison.

HttpRange14Webography – A chronology of discussions about the HTTP range-14 issue.

Media Type Specifications and Registration Procedures – “This document defines procedures for the specification and   registration of media types for use in MIME and other Internet   protocols.” (IETF draft – N. Freed, J. Klensin, T. Hansen)

HAL – Hypertext Application Language: A lean hypermedia type for RESTful APIs – “HAL is a simple, generic hypermedia type based on JSON and XML for use in RESTful APIs. Essentially, HAL provides a set of conventions for expressing hyperlinks to, and embeddedness of, related resources – the rest of a HAL representation is just plain old JSON or XML. HAL consists of two reserved elements: Resource and Link. Any and all elements are legal in a HAL representation provided they do not conflict with HAL’s reserved elements.” (by Mike Kelly) + a comments thread on the REST mailing list

We live in a POST REST/SOAP World – “we now live in a POST REST/SOAP world. Converged (Mobile) Applications have pushed the envelope of what distributed computing should do and how it does it. Never HTTP or SOAP were really prepared for 3-legged authentication, respect privacy and support monetization at the scale of several billion API calls/month. Actually SOAP was a bit more prepared since a message could have a number of security tokens representing different principals, but who cares, we were told that HTTP was the answer, because it was “RESTful” so now we struggle with all kinds of three-legged authentication mechanisms.” (by Jean-Jacques Dubray)

designing a RESTBucks media-type – (by Mike Amundsen)

How Offline Web Apps Should Work – “The essence of this proposal is that a proper solution to the offline web app problem should not require drawing a distinction between “offline” and “online” assets. There is no need for ‘cache manifests’, or to create a separate ‘application cache’ from the standard browser cache.This solution should leverage existing web caching infrastructure (i.e. HTTP headers such as Cache-Control, Etags, etc) to control how browsers store and negotiate the assets required to run the application offline.” (by Mike Kelly)

The trouble with APIs – “1. REST APIs are a case of good intentions run amok. The point of REST was to *eliminate* specific APIs. Not cause their proliferation. 2. When someone says you shouldn’t document a REST API, they’re saying you shouldn’t have an API. Not that you shouldn’t document. 3. That said, RESTians saying you shouldn’t have an API are somewhat vacuous because they offer no good alternative. Custom media types ain’t. 4. Thus, IMO, until we have a workable generic media type or two for the 80% case of “REST APIs”, we’re just growing a frustrating mess.” (by Stuart Charlton)

The Good, the Bad, and the Ugly of REST APIs – “Adrian Cole of jclouds and I have written a lot of code against a variety of SOAP and REST cloud computing APIs. We’ve seen a lot of the good, the bad, and the ugly in API design and we tend to complain to each other about the things we dislike. This article sums up my thinking on the subject (not necessarily Adrian’s, though Adrian reviewed the document and gave me additional ideas).” (by George Reese) + a comment post from William Vambenepe.

Providing and discovering definitions of URIs – “A few widely known methods are in use to help agents provide and discover URI definitions, including RDF fragment identifier resolution and the HTTP 303 redirect. Difficulties in using these methods have led to a search for new methods that are easier to deploy, and perform better, than the established ones. However, some of the proposed methods introduce new problems, such as incompatible changes to the way metadata is written. This report brings together in one place information on current and proposed practices, with analysis of benefits and shortcomings of each.The purpose of this report is not to make recommendations but rather to initiate a discussion that might lead to consensus on the use of current and/or new methods.” (by Jonathan Rees)

What REST needs to do to succeed in the enterprise – “In the spirit of constructive criticism here is what REST needs to do in order to succeed in the enterprise and B2B markets, the sort of markets that make actual revenues and profits as opposed to hype markets with the stability of a bubble. First off there is the mental change required, four steps here. Focus on how people and especially teams work. Accept that HTTP isn’t a functional API. Accept that enterprise integration, B2B and Machine to Machine require a new approach. Accept that the integration technology isn’t the thing that delivers value.” (by Steve Jones)

REST isn’t undead in the enterprise… its still born - ”All this just proves what I’ve said for a long time. REST works for information traversal, but its not set up for the enterprise. So what is the issue with REST not displacing SOAP in the enterprise? …. REST needs a standard way to publish its API and for a way to notify changes in that API. This is a “solved” problem in IT but for some reason the REST community appears to prefer blaming others for the lack of enterprise success of their technology rather than facing up to the simple reality…” (by Steve Jones)

All About EVE: Extensibility, Versioning, Evolvabiility, etc. through Modifiability – Excellent presentation slides on versioning and evolvability in (RESTful hypermedia) systems. (by Mike Amundsen)

REST mailing list

Definition of a Hypermedia Client – excellent attempts at defining a hypermedia client.

Stateful APIs – “Consider a simple photo storage service as an API. Users can only interactwith the API if they’ve got an account. Let’s say authorization happensoverHTTP Basic. Given that, would you use URIs like /photos and /photos/{id} (as a photo listand photo detail resource, respectively)? What’s weird about those URIs isthat my /photos is a different list of photos than your /photos — in otherwords, the resource represented depends on the information intheAuthorization header.”

Events

ICWE2011 – The 11th International conference on Web engineering was held at Paphos, Cyprus. Check out the program page for the list of presented papers and the workshops page for the list of workshops. I didn’t go through the papers from all the workshops yet, but at lest 2-3 papers from the main conference should be interesting in the context of REST:

• Irum Rauf and Ivan Porres. Validating Behavioral RESTful Interfaces using Semantic Web Technologies
• Kamara Benjamin, Gregor Bochmann, Mustafa Emre Dincturk, Guy-Vincent Jourdan and Iosif Viorel Onut. A Strategy for Efficient Crawling of Rich Internet Applications
• Ivan Zuzak, Ivan Budiselic and Goran Delac. Formal Modeling of RESTful Systems Using Finite-State Machines (draft of full paper is here, presentation slides are here)

The proceedings of the conference are published by Springer, but I’m sure that Googling for paper titles will also go a long way.

Interesting tweets

@svrc – “REST APIs are a case of good intentions run amok. The point of REST was to *eliminate* specific APIs. Not cause their proliferation.”

@sallamar – “What the discussions about failure/success of REST are missing – (a) that REST is NOT prescriptive and so don’t try to make it prescriptive”

@svrc – “When someone says you shouldn’t document a REST API, they’re saying you shouldn’t have an API. Not that you shouldn’t document.”

@pkeane – “theory: value (+ maybe RESTfulness) of an API can be measured by how easily I can open a representation in a text editor & make sense of it”

This Week in #REST – Volume 36 (Mar 27 2011 – May 30 2011)

This is Volume 36 of This week in REST, for Mar 27 2011 – May 30 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! P.S. sorry for being away for 2 months… lot’s of stuff happening at work so blogging got pushed down the priority stack.

Around the Web

A REST wankery question – “Given that, would you use URIs like /photos and /photos/{id} (as a photo list and photo detail resource, respectively)? … It seems like URIs like /people/{my-uid}/photos and /people/{my-uid}/photos/{photo-id} are more “pure.” But now that’s weird because only one single user ever has access to a given URI (e.g only user #7 gets to access the entire space under /people/7).” (by Jacob Kaplan-Moss)

Identifying Application State – W3C Working Draft: Proposed TAG Finding  ”This document explores the issues that arise from the use of fragment identifiers to identify application state and attempts to define best practices.” (by T.V. Raman, Ashok Malhotra)

Web APIs: Don’t be a victim of your success - “As developers, we are used to dealing with unforeseen problems, we just fix them and redeploy.  However, APIs are different beasts, because the applications that consume the API are often not written by an external developer.  Making significant changes is likely to impact clients, and breaking clients not only annoys the client developers but also the users of those clients.  It’s just not good for business.This article discusses approaches you can take upfront, that will minimize that chances of breaking clients as your API evolves to meet the crushing demands of success “ (by Darrel Miller)

evolvable systems - ”How can we design and implement distributed network solutions that remain stable and flexible over time? … my assertion is that one successful approach invovles a combintion of accepting and embracing some realites of dist-net architecture, isolating the key transient aspect of the environment, and focusing most of your creative eneregies on expressing the vital problem domain information in a flexible and evolvable way.” (by Mike Amundsen)

Scanning data with HTTP – “As part of my series on SCADA and REST I’ll talk in this article a little about doing telemetry with REST. There are a couple of approaches, and most SCADA protocols accidentally incorporate at least some elements of REST theory. I’ll take a very web-focused approach and talk about how HTTP can be used directly for telemetry purposes.” (by Benjamin Carlyle)

Why and How You Should Write REST-Centric Applications – “Ever since Twitter built their “New Twitter” UI on top of their existing API, the idea of incorporating the very same philosophy into my own applications resonated with me. I decided to move forward with the same approach and my team and I been doing so since September. For those of you that have not taken this route, what I’d like to do is share some of the reasons why you may want to, and some advice on how to make it relatively painless. ” (by Michael Woloszynowicz)

SOA in 2011 Panel - ”Many companies embarked on servicizing their software implementations and some achieved great success, while others failed. SOA was on the top of analysts’ reports, then was proclaimed dead and then reborn under slightly different names – REST, cloud computing, etc. There are literary thousands of SOA books and articles covering many aspects of SOA from architectural design to nitty-gritty implementation details. In this virtual panel, InfoQ talks to 5 SOA experts about the significance of SOA, its relationships with other architectural styles, best technologies and approaches used for successful implementations of SOA solutions and SOA future.”

How do you measure the RESTful-ness of an application? – “Over the past few years it would be hard to ignore the rise in popularity for using RESTful approaches to building enterprise applications. Now we seem to have moved beyond the REST vs WS-* debates, or whether or not REST and SOA are complimentary, to discussions around the maturity of REST-based implementations. Unfortunately it seems that even this could be an active area of confusion, debate and disagreement. When discussing maturity and REST in the same sentence, some individuals refer to the Richardson Maturity Model as the right approach to measure against. For instance, in his recent article Martin Fowler discusses the various levels in the model”

List of ways HTML can download a resource – “Recently two different projects required compiling a list of ways to trigger a download through HTML: Resource Timing and Preload Scanner optimization.There’s no centralized list in the WebKit source nor did a web search turn one up. So in hopes it may be useful to others, here’s what I was able to come up with. Please let me know what I forgot (note that ways to download through CSS, JS, SVG and plugins are intentionally omitted).” (by Tony Gentilcore)

Information Resources and Web Metadata – “This note considers the semantics of metadata in which the subject of the metadata (the “data”) is specified using a URI that may be dereferenced on the Web. This situation is complicated in that agents might obtain different information on different dereference operations, raising the question of what metadata is true or not of the metadata subject.It is proposed that the practical purpose of the “information resource” abstraction in web architecture is mainly to supply suitable subjects for this kind of metadata. Relating information resources to metadata in this way makes concrete the value proposition for the rule that a URI should name the information resource related to dereference of that URI. It is hoped that this analysis will be of use in future work aimed at strengthening or modifying consensus around this rule. ” (by Jonathan A. Rees)

Links Don’t Open Apps – “The realization that links don’t open apps has triggered for me a renewed appreciation of the power of hyperlinks. When people talk about the differences between native apps and mobile web, they usually talk about difference like performance, cross platform development, and other technical factors.” (by Jason Grigsby)

Mature REST In Six Lines! – “Like Subbu, I also have been sitting on a blog post about the Richardson Maturity Model. I have different reasons for feeling uncomfortable with this Model, however.The following came out of a discussion on an internal list at ThoughtWorks, where a number of people were talking about how they aspired to reach the “Holy Grail” of REST Level 3, and still thought they were basically “doing REST” by addressing most of the uniform interface.But, as indeed pointed out in that article, REST is only at Level 3.However, fortunately, you can jump right to Level 3 without much effort.” (by Duncan Cragg)

Webmachine and RESTful Web Frameworks with Justin Sheehy – (video) “Justin Sheehy discusses the benefits of RESTful web frameworks and how these apply to the Webmachine toolkit. He also talks about security, debugging and the future of web frameworks and HTTP.”

Using DNS for REST Web Service Discovery – “The use of the REST architectural style is steadily gaining momentum for both public facing Web services and enterprise integration. However, one aspect of a service oriented architecture does not yet receive sufficient attention: Service Discovery. In this article, I will describe how existing Web technology can be leveraged to enable Service Discovery for RESTful Web services.” (by Jan Algermissen)

Measuring REST - ”Don’t follow models like Richardson’s Maturity Model to decide whether your app is RESTful or not.Why not? The reason is quite simple. We build software to do something of value while accounting for some quality attributes (or “ilities”). In the case of RESTful apps, how you prioritize a given set of quality attributes can help you choose the right set of constraints. Period. ” (by Subbu Allamaraju)

Atom Content Negotiation – “let’s assume you have a collection of items that is exposed via feeds and managed in whatever back-end storage works well for you. you want to be a good web citizen and publish it as HTML, XML, JSON, and RDF. you also want to be a good web service citizen and publish any updates via feeds, so that consumers are notified whenever the collection changes. what is the best web pattern to do that? i am wondering what the more popular approach is, and why. i am also wondering whether it might be worth the effort to have a small extension that would make this more reliable in the sense that there would be a link relation for interlinking feeds that carry the same content, but using different content types.” (by Erik Wilde)

My PUT Requests Bug Me – “So here I am, writing documentation for some new GitHub API sweetness, when something strikes me. Why are we using PUT requests for updates? Should it bug me that my API uses the PUT verb?” (by )

Events

W3C Workshop on Identity in the Browser – Papers from the W3C Workshop on Identity in the Browser, 24/25th May 2011, Mountain View (USA).

Interesting tweets

@AndrewWahbe – “Henry S. Thompson: “architecture of the internet is concrete while the architecture of the web is abstract” #IETF80“

@AndrewWahbe – “Rosenberg: web model is becoming the same (proprietary protocol) with a mechanism for distributing software #IETF80“

@wmartinez – “Good faces on Interoperability and Modifiability for REST. Sad face for Performance and Reliability. Merson. #soacloud“

@mamund – “RT @dret: “a need for Uniform Data?http://bit.ly/jFzT9h (by @webr3) ; no, a uniform interface & media types work just fine.” #REST +1″

@algermissen – “From chat with @mamund:Media types should specify which kindsof links refer to resources with bookmarkable URIs. Or is there a way to guess?”

@dret – “really hope for #www2012 to be less about mining web content, and more about web architecture and web as a platform. architecture matters.”

@fielding – “@mnot I have a much better test page for deciding whether a site is truly RESTful or not: http://s.apache.org/FKu“

@WSREST2011 – “”the state sandwich: application state machine, hypermedia state machine, HTTP state machine, media state machine.” @svrc #wsrest2011“

@WSREST2011 – “look out for “Behave”, to be released by @svrc in may 2011. #wsrest2011“

@WSREST2011 – “”main difference between programs an agents: agents act in an environment, agents are goal-oriented and autonomous.” @svrc #wsrest2011“

This Week in #REST – Volume 35 (Mar 7 2011 – Mar 26 2011)

This is Volume 35 of This week in REST, for Mar 7 2011 – Mar 26 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

Is it RESTful? – “This site helps people to figure out if their Web site and APIs are RESTful, by interactively interrogating them and applying a suite of cloud-based analytics. Or, it gives a completely random answer.”

Nobody uses the term “web services” anymore. – “Apropos revising RESTful Web Services, I have a question for you. When I started talking with people as part of my job search, I noticed that nobody uses the term “web services” anymore. Everyone talks about “APIs”.”

Trends in Web Applications and the Implications on Standardization – “Advancements in the design of web browsers have introduced   fundamental changes to the architecture of application protocols.   The widespread availability and growing sophistication of JavaScript   interpreters in browsers enables web servers to push to browsers all   of the application logic required to implement a client-server   protocol.  Consequently, many client-server applications that once   required an installed client on a host computer now can rely simply   on a modern browser to act as a client for the purposes of a   particular application.”

IETF technical plenary: the end of application protocols – “As described, the session suggests a failure to recognize at least two architectural issues. One is that it mandates full-time connectivity.  The other is that protocolsthat it says are no longer needed are in fact still needed in some form, albeitas a layer above HTTP, rather than TCP.”

AJAX is the new NAT – “What we need to do is acknowledge that AJAX has happened. The Web hasn’t been “hypertext” for a long time now.”

BPM with REST – “Cesare Pautasso discusses the conceptual relationship between business processes and stateful RESTful services, showing how BPM can be used to design and implement hypermedia-based services.”

Give me a REST, I just want to get my Message across – “When you start building applications on top of WebSockets (and degrading) you also start to think about different architectures. WebSockets gives us a rich, fast, bi-directional pipe between the client and server. Whether you are a Socket.IO lover with Node++, or an Enterprise sort on Kaazing, you can start to deal with a very simple messaging API (that degrades).”

Resource Identification and Query Parameters in URIs – “An interesting topic came up at QCon London: What identifies a resource? One view is that resources in REST are identified without considering the query parameters in the URI. In most RESTafarians’ view, none of the characters in the URI should have special meaning. But even if one happens to agree with this, it’s still interesting to find out what the specs actually say.”

Microsoft gets serious about Http – Presentation by Darrel Miller.

state transitions: simple and complex – “it’s easy to get bogged down in what state transitions “are”, how they “work”, and their role in hypermedia and the Web in general. i’m going to skip over all that here[grin]. instead, i want to focus on some of the concrete details of state transitions for hypermedia and why i think identifying them is critical for building robust distributed applications.”

Repurposing the Hash Sign for the New Web – “The Hash sign (#) in a URI was originally used to introduce a static “fragment identifier”, but recently it is being used in many more complex ways as it is set by and interpreted by JavaScript in Web applications. Fragment identifiers are used to provide several different kinds of parameters to the client-side application, such as the actual URI of a video to be played to a video player, or the position and zoom to a map. Unlike search parameters preceded by “?”, the characters in the URI bar after the “#” can be changed without causing the page to be reloaded. Applications and toolkits using fragment identifiers in this way often go to some effort to maintain a history and make sure the back button works as expected. Accessibility and search can, however, be compromised because without running JavaScript, the URI has no meaning. Such uses of the “fragment identifier” have interesting and different properties, and differs from the way it is currently described in specs. This document explores the issues that arise from these new uses of fragment identifiers, and attempts to define best practices.”

Documents in applications – “It has become fashionable to divide Web resources into two broad categories: each resource is either a document, rendered primarily in HTML, or an AJAX-style  Web application that uses Javascript to facilitate very dynamic interaction, navigation and information retrieval.  My purpose here is to argue that we need to be more careful, that many AJAX applications in fact provide access to documents after all, and that the Web would be much more robust if we took some care to identify and access those documents using the same sorts of URIs that we use for other Web documents.”

Managing Relationships between Resources with URIs - ”The big benefit of systems based on addressible resources is that the resources are identified by portable URIs. The big payoff is that, unlike database primary keys, the identifiers are usable in a much broader context than just that system itself. In most cases, those URIs are, in fact, URLs. But since they are addressable, we’re not limited by things like PK values or names that only our system understands. We can share those identifiers between disparate systems.”

REST, Hypermedia, and Query Strings – “Now, I agree totally that the path part of the URI — that is, everything in front of the first “?” or “#” should be treated as an immutable, opaque string. That’s just saying that the server controls that part, and can change it at a moment’s notice. The client must be decoupled from the path of the URI. But the query string part of the URI is not so clear.”

Hash URIs – “Having looked at the advantages and disadvantages, I would echo what seems to be the general sentiment around traditional server-based websites that use hash-bang URIs: pages that give different content should have different base URIs, not just different fragment identifiers. In particular, if you’re serving large amounts of document-oriented content through hash-bang URIs, consider swapping things around and having hashless URIs for the content that then transclude in the large headers, footers and side bars that form the static part of your site.”

Events

WS-REST 2011 – Preliminary proceedings for the WS-REST workshop have been published online.

This Week in #REST – Volume 34 (Feb 9 2011 – Mar 6 2011)

This is Volume 34 of This week in REST, for Feb 9 2011 – Mar 6 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

Long Bets: PREDICTION 601 – “The original URL for this prediction (www.longbets.org/601) will no longer be available in eleven years. ”Cool URIs don’t change” wrote Tim Berners-Lee in 01999, but link rot is the entropy of the web. The probability of a web document surviving in its original location decreases greatly over time. I suspect that even a relatively short time period (eleven years) is too long for a resource to survive.I would love to proven wrong.” (by Jeremy Keith)

Principles of the Same-Origin Policy – “The security model of the web platform has evolved over time to meet   the needs of new applications and to correct earlier mistakes.   Although web security has evolved largely organically, the security   model has converged towards a handful of key concepts.  This document   presents those concepts and provides advice to designers of new   pieces of the web platform.” (by Adam Barth)

Design Considerations for Protocol Extensions – “This document discusses issues related to the extensibility of Internet protocols, with a focus on the architectural design considerations involved.  Case study examples are included. It is intended to assist designers of both base protocols and extensions.” (by B. Carpenter, B. Aboba and S. Cheshire)

More on PUT Idempotency – “One of those conversations was started with a reference to a really good blog post from Alex Scordellis addressing the question of how complete representations sent in a PUT need to be. What exactly does the client need to include in the representation that they PUT – all properties? what about hyperlinks? A simple answer might be that they need to provide “everything”, but this simple answer is just not satisfactory.” (by Cornelia Davis)

Headless Foxes – “If a server is just a browser instance and the client is a browser instance then this completely changes how a web developer can think about development and debugging. What if Firebug was a server itself? You made AJAX calls to it, and it ran the “server-side” JavaScript in your browser, the same as it would on a live server. No longer would you be tied to the infrastructure of your live environment.”

my boundary issues w/ hypermedia – “as a result of my efforts to refresh my concept of hypermedia and it’s role in distributed network applications, i’ve come to view the messages passed between client and server as containing several distinct sets of information. these are: Protocol information … Domain information … State information …” (by Mike Amundsen)

i have an experiment; will you help? – “in this experiment multiple parties must build client and/or server applications to match a spec; all w/o seeing each other’s work. IOW, there is no “sample” running somewhere. in addition, the “application” uses XHTML as the base media type (sorry, no custom media type this time[grin]). finally, the only instructions for this experiment are found in a single document that contains the “semantic profile” of the target web application expressed via selected XHTML attributes (@class, @id, @name, and @rel) along with “valid values” for these attributes, descriptions of how they are used in representations, and “what these values mean.”" (by Mike Amundsen)

Principles and Patterns of Organizing Systems – New (?) course at Berkeley with slides and material being posted as the semester progresses: “The concept of an organizing system complements this categorical view with a dimensional perspective that sees these categories as sets of design patterns that reflect typical answers to questions about what is being organized, why, when, how much, who is doing the organizing, and how services are provided to interact with the organizing system. These dimensions frame trade-offs and constraints about the content, policies, and implementation of organizing systems. The primary goal of this course is to use these design dimensions to better understand traditional design patterns and their consequences, and to identify useful new ones.” (by Erik Wilde and Robert J. Glushko)

RESTful SOA in the Real World – (video) “Sastry Malladi presents different ways used by the industry to implement a RESTful SOA, detailing how eBay did it in order to achieve performance, and what lessons can be taken from that.” (by Sastry Malladi)

What is REST, Anyway? – “…so I’ve been spending some time reading more about REST, refining my thinking, and opinionizing a lot on this blog.I finally came to the conclusion that REST is not what a lot of people treat it as. It’s not a standard you can write a strict spec for, and then apply it to projects and declare “Yay!” or “Nay!” People do that, and that practice sinks a lot of projects, because it’s a silly practice.”

REST in the design, use, and documentation of Web APIs – Slide deck for intro-level REST presentation at DHapi (by Peter Keane)

This year in #rest on Freenode – Word cloud of chats from the #rest channel on Freenode. (by Kevin Burns Jr)

Calculated vs. Shipped URIs – “I wonder about the effenciencies, though. CPU is cheap and fast, bandwidth is slow and (kind of) expensive. So publishing a URI spec out-of-band and letting the client construct the actual URI with string concatenation consumes very little runtime resources. But shipping big documents loaded with hyperlinks, millions and millions of times, is going to be expensive.”

Client-driven APIs – “I lot of the REST conversations I’ve seen get tangled up because they are trying to constrain their Resource definitions too tightly, and end up restricting what the client can get at, making the client make lots of calls to get what they could get at once. Or they go the other extreme, and make Resource definition so incredibly broad that every Resource in the system meets every need that we could possibly anticipate from the client, making every response huge, bloated documents that take a long time to code, maintain, and support the bandwidth for.”

Designing RESTful Domain Application Protocols – Slide deck for presentation at JFokus: “REST is ready for the enterprise. Imagine an information platform that is open and available to systems throughout the enterprise estate. A platform that eschews integration in favour of composition, connected data over siloed databases. A networked data structure with the power to implement valuable business behaviours: a distributed, hypermedia-driven application platform. Challenging the notion that REST is suitable only for simple CRUD-based data services, in this session I show how to design and implement RESTful domain application protocols for complex business processes. With a detailed example, I show how to: – Model business processes as domain application protocols – Implement them in terms of resource lifecycles – Advertise and execute them using HTTP idioms, media types and link relation values” (by Ian Robinson)

Dog or Tail: REST or Hypermedia? – “My personal opinion is that as the tools to support hypermedia evolve, REST as we know it today is going to become a side discussion. That the principles of REST will be just small part of the discussion on how we deliver hypermedia. A few examples of why I think that are: …”

HTTP Headers – “This is a continuation of work started by Brough Davis as part of his software security project for his Masters in Information Security Engineering. The main goal of this project is to find how many sites use security relevant headers, like for example the X-XSS-Protection or X-Frame-Options headers.”

Web Apps and Web Sites – “What’s the real tradeoff in the hashbang case? The tradeoff here is between usability of two classes of clients – one that does not support Javascript and the other that supports. That’s a reasonable tradeoff! Twitter chose to not render http://twitter.com for non-Javascript browsers. Perhaps they made that by choice by looking at the proportion of users that use non-Javascript browsers.” (by Subbu Allamaraju)

A simple overview of httpRange-14 – “Complicated issue eh? it’s certainly consumed a great deal of my time for over a year.So, here’s a simple-ish summary of the problem – disclaimer, all IMHO of course…” + The simplest view possible of httpRange-14. by the same author.

Minutes from the March 03 telcon of W3C TAG + Minutes from the 8-10 February 2011 TAG F2F Meeting

Events

WS-REST 2011 – The list of accepted papers for WS-REST 2011 has been published. However, not all reviewers are happy with this year’s submissions. The workshop keynote will be given by Stu Charlton, you can see his sneak peek for the talk here.

ComposableWeb 2011 – “the 3rd International Workshop on Lightweight Integration on the Web (ComposableWeb 2011) will be held in conjunction with the 11th International Conference on Web Engineering (ICWE 2011) in Paphos, Cyprus, from June 20-24, 2011.”

WEWST 2011 – “The Workshop on Enhanced Web Service Technologies (WEWST), collocated with the European Conference on Web Services (ECOWS), is the premier workshop for academic and industrial communities to discuss innovative ideas and research contributions advancing the state-of-the-art in Web service technologies.” Will be held on September 14, 2011, Lugano, Switzerland.

Discussion groups

Django REST framework – Critical feedback wanted. – Discussion on new Python REST framework for Django: “Django REST framework is a lightweight REST framework for Django, that aims to make it easy to build well-connected, self-describing RESTful Web APIs.”

Cross-Origin Resource Embedding Restrictions – Discussion about an idea and specification for “…defining a way for resources to declare they are unavailable within an embedding context.”

Review of TAG issues related to “URI meaning” (long) – Overview of W3C TAG issues related to the problem of “URI meaning”.

Conversation about “Web Applications Architecture” additional background for TAG discussion

Loose coupling – a RESTful myth? – “It is often stated, that RESTful services decouples client and server, as e.g. stated here [1]:”Coupling between client and server is removed, server owners need not know about client particularities to evolve the servers without breaking clients.”But i think, the most server changes will break even the RESTfuls´ clients.”

Link header is representation metadata? – “Sorry but I need to come back to this one, can I get a definitive answer (please :)) on whether the Link header is representation metadata (like Content-Type), or not?”

Software frameworks

CRest – “CRest (Client Representational State Transfer or Client REST) is a lightweight framework aiming to simplify the integration of external REST services into java applications, somewhat in the way most of the current SOAP WSDL oriented client framework works.While SOAP is a protocol, based on a service descriptor format (WSDL) that can be used to automatically generate the client stubs, REST isn’t, and REST service implementation varies from one provider to another.CRest allows the developer to only focus on the essential aspects of the integration of a REST service.”

Interesting tweets

@kriszyp – “HTTP response of the future when you visit a site? https://gist.github.com/853195“

@AndrewWahbe – “Hash Bang URLs are a symptom, the problem is that nobody is trying to extend markup to do simple AJAXy things declaratively”

@jerenkrantz – “With due respect to @timbray & @fielding, #! in URLs indicate where REST falls down: computations – rather than documents – are exchanged.”

@fielding – “@jerenkrantz Making it easy for Web developers to create fragile, unreliable, and unsharable Web experiences is not a goal of REST.”

@mikekelly85 – “#REST is about agreeing on the best way for machines to facilitate human interaction and stay out of the way”

@dret – “finding it interesting that one of the most universal human actions (going to) has become a synonym for HTTP GET.#REST #uniforminterface“

@svrc – “Trying to craft a RESTful service discovery approach with the XRD/host-meta/LRDD stuff. Finally the last nails in the UDDI coffin.”

@dret – “don’t fall prey to the dark side of where the functions lurk. focus on resources you must, and links will guide your path.#REST“

@aslak_hellesoy – “WebSockets are throwing the baby out with the bathwater. Server Sent Events/EventSource and REST seems a much better stack.”

@dret – “if i can link to and reuse resources from your server, you’ve built a web app. otherwise, you’ve just built an app using browser APIs.”

@dret – “discovered that #REST can be nicely illustrated with menus, restaurants, orders, food courts, pending orders, special requests, and: food.”

@mamund – “RT @iansrobinson: @dret “… I want some term for the specialisation that helps us get things done.” <- application semantics?”

@jar346 – “”representation” is hateful not because I hate people who use it, but because its multiple definitions make you fight one another!”

@iansrobinson – “@dret Resources don’t come into it, cause I don’t think resource types are useful; resources are just sinks and sources for representations”

@iansrobinson – “@mamund Disagree that custom media types have, or ought have, PS – that’s the role of a protocol! See AtomPub (which is not a media type)”

@svrc – “@iansrobinson … because I believe custom media types are inherently the wrong long-term direction; they’re the symptom of a gap”

@mikekelly85 – “@iansrobinson media types and link relations are just another part of a uniform interface; they all provide conditions for discoverability”