subbu.org

POST Caching Example

2008-11-18T22:25:10Z

Here is a good example of caching of POST responses by Henrik Nordström in the HTTP WG.

The classic example of where a cacheable response to POST makes sense is the guestbook example (or unmoderated blog comments for those needing a more modern example, basically the same thing in a different era) where the visitor POSTs an addition to the page currently viewed, or “separate entity that accepts annotations” as it’s expressed in the RFC. The response given to the POST is the new representation of the page. Both
GET and POST uses the same URL in this example.

followed by

Note that the POST request as such can never be satisfied from cache. A repeated POST with the same form content will not yield the same result even if the response is cacheable.

The context of this thread was whether the HTTP method should be included in the cache key. See this thread for a complete summary.

Analytics for Web APIs

2008-11-18T04:44:16Z

Runtime linking in RESTful apps can reduce client-server coupling as the server can tweak the workflow at runtime without completely breaking client apps. Here is one more reason to switch from static pre-published URIs to runtime linking.

Say, you built a cool Web API. Folks are excited about your API are are actively using it. You now have some better ideas, and want to find the effectiveness of some options you have. How do you go about testing the effectiveness of each option before flipping on the big switch?

For consumer-facing web apps, A/B testing provides an effective technique for segmented testing of various design/implementation options. Here is one simple way to build hooks for A/B testing into web pages.

  // Embed test variables into links.

  trackId = createLink(<some ID>, <some test variables>);

  // Store test variables for later analysis

  storeTest(trackId, <test variables>);

  // Render link

  ... + "&track=" + trackId + "...";

This may produce a URI like the following.

  <a href="http://example.org/blahBlah?someParams&track=xyz>...</a>

Subsequently, when a user actives this link, the server can correlate that link to the test variables used. This correlation data forms the basis for post-hoc analysis for A/B and other forms of bucketed testing.

By using runtime linking for Web APIs, i.e., by making them take advantage of the HATEOAS constraint of REST, we can use the same technique for correlating API calls to test variables and conduct A/B testing. That is, when clients are discovering URIs at runtime based on known link relations, servers have a chance to get smarter.

Directory Structure-like URIs

2008-11-13T01:05:04Z

Alex Rodriguez in RESTful Web services: The basics says:

REST Web service URIs should be intuitive to the point where they are easy to guess. Think of a URI as a kind of self-documenting interface that requires little, if any, explanation or reference for a developer to understand what it points to and to derive related resources. To this end, the structure of a URI should be straightforward, predictable, and easily understood.

What is interesting is that, the example cited in this paper carefully tries to skirt around the problem of how a client can determine what a URI is supposed to do. Well, if the structure of the URI is such that it is self-describing, the problem is solved. Right? Sorry Alex. No. The answer is linking. This is unfortunate, coming from IBM Developer Works.

Here is a more interesting advice:

Instead of using the 404 Not Found code if the request URI is for a partial path, always provide a default page or resource as a response.

I wish he tried to explain this with an example, as that would have allowed him to see the consequences of masquerading errors in success responses.

Who is Composing Your App?

2008-11-16T05:36:00Z

As I was debating some comments with JJ over the weekend on a paper that I am writing on describing RESTful applications, the question on composition came up. In particular, who is composing your app? The server? Or the client? The context of our discuss was the difference between describing the contract of a RESTful application vs describing that of a web service (the SOAP kind) using WSDL.

In the SOAP-land, services express their interface via WSDL documents. A WSDL is nothing but a group of message exchange patterns, expressed in a context-free manner. Each pattern accomplishes some discrete function, which may or may not be interesting and useful on its own. Clients combine various message exchange patterns into an application to accomplish something of value. For instance, an app doing implementing some HR functions may be talking to some payroll services. Only the client knows the context in which it is using those payroll services. As far as the payroll service is concerned, it is just “message in and, optionally, message out”. It does not know what the client is trying to accomplish.

In this model, how does the client know how to compose such services into its application? In particular, how does it know whether it is okay to send a particular message “M” to a service “A” before sending message “N” to a service “B”? WSDL does not have this info. So, it has to make some assumptions either on its own, or rely some composition framework or language (like BPEL). In either case, the service does not have much to say.

In the REST-land, resources rely on the uniform interface, media types, and links to express the contract. More interestingly, the links that the server provides inform the client of what it can do subsequently. That is, the links in a representation let the server incrementally express the interface between the client and the resources it is interacting with.

In this model, the contract is contextual. The client does not make assumptions about this contract. Nor does it need an external composition framework. If it finds some links with some known relations, it means that it can do certain things. If, at a later stage, it does not find those links, it means that it can not do those things.

This is an important difference worth calling out, as it has a number of consequences:

The same client/server code can not support both REST and WS-*. Code sharing may be possible at lower levels, but not at the application level. This is where I don’t agree with Alan Dean’s statement that a system can compose both REST and WS-*. I hope I am interpreting his statement right. The differences between client-side and server-side processing are significant enough to demand code isolation.
A RESTful server can change or finetune the contract at runtime. So, the client must be prepared to accept changes in the workflow at runtime.
A RESTful server can move resources around or even upgrade resources in a compatible manner at runtime, and a RESTful client will not even notice such changes.

Thanks to JJ for his time.

Please Vote for “That One”

2008-10-30T02:59:38Z

I live in the US, but I can not yet vote in this country. If you are passing by this blog, and can vote, here is my request. Please vote. Please vote for "that one".

Sorry - closing comments for this post.

Comments on SOFEA

2008-10-28T18:46:04Z

In the same session on "RESTful Web Apps", I briefly discussed about SOFEA and some offshoots like Appcelerator. Here is a follow up thread.

JSF is Not Fixable

2008-10-28T15:45:58Z

Last week, at the Colorado Software Summit, I gave a session on RESTful Web Apps. In this session, I made a comment that the proponents of JSF failed to consider the web architecture, and that it is not fixable. My goal in that session was to point out the consequences of design choices made by some web frameworks, but not necessarily to point fingers at those frameworks.

Matt Riable attended my session, and shared his notes on his blog at RESTful Web Applications with Subbu Allamaraju. His post incited some comments, to one of which I would like to respond here.

Diego Plentz said that

I haven't come to the conclusion that JSF is not fixable yet. It looks like there are some major overhauls going on related to state saving and RESTful URLs in JSF 2.0.

I think this comment misunderstands what it means to be "RESTful". The ability of an app to create a link that can be submitted via GET to some non-JSF app does not make the app RESTful. Period. I don't have problems with JSF focusing on usability, but I do think it should have paid attention to the web architecture. Given that JSF is a Java standard, those who want to rely on standards have no choice but to build web apps that fail the web architecture and can not take advantage of common web infrastructure. The design choices made in JSF are poor, and I don't see an exit strategy other than dumping the current standard, and going back to the drawing board. Bill de hÓra echoed a similar thought:

But it’s hard to be non-critical about a spec that got things so wrong - not just REST, but basic HTTP usage. A JSF that supports REST is going to be a complete overhaul, no?

I have not read the latest JSF 2.0 draft thoroughly, but upon a quick reading of all the changes, I don't see anything to address the basic web usage. Unless there are more changes coming that will magically fix the core without an overhaul, JSF should the follow JAX-RPC into the JSR-graveyard.

Update:

Looking at some of the heated comments below and the links posted, I can't help but comment that JSF (community) has recently discovered the web architecture, viz., that GET is the de facto means of navigation and that POST is an exception and used solely for unsafe and non-idempotent operations. This is unfortunate for a standard. Secondly, the ability to pass parameters to a URI does not fix JSF as long as JSF's notion of a form is always driven by POST. That does not make JSF a bad framework, it just makes it a special-purpose framework that can be used to build certain kind of stateful applications. That, IMHO, is a too low a bar for a standard framework.

Slides from the Colorado Software Summit

2008-10-28T17:21:31Z

I spent last week at 9300ft above the sea level at Keystone (CO) attending the Colorado Software Summit. This is one of the best conferences I have attended in a long time, with just about 300 attendees and serious sessions with very little fluff and absolutely no product/vendor pitch of any kind. This is one conference that I can recommend to any one who value their money and time spent on conferences.

Here are the slides for my sessions:

Pragmatic REST: This session is about building HTTP APIs RESTfully.

Pragmatic Rest

View SlideShare presentation or Upload your own. (tags: rest)

Here is the link to download a PDF version.

RESTful Web Apps: This session is about the RESTful aspects of the web, and how certain mainstream Java web frameworks make it harder to build web apps that play nice with the web architecture. My slides for this session are not as polished as I would have liked, but well - that's all the time I have.

RESTful Web Apps - Facts vs Fiction

View SlideShare presentation or Upload your own.

Here is the link to download a PDF version.

Where Do Resources Come From?

2008-10-28T15:47:58Z

Here is the approach I used in my session at the Colorado Software Summit on REST (I will post the slides over the weekend) to find resources.

Domain Nouns: This is the most natural approach for finding resources, but it can end up with an inconvenient resource model. For instance, the NYT Movie Reviews API has things like Movies, Reviews, Critics, Critic's picks, Reviews by reviewer identified as resources. These can provide a good starting point, but may not meet the needs of client apps, which leads to the next step.
Composites: These are combinations of other resources, created primarily to address client app needs. Composites can also fix the urge for batching. An example is "a user profile with 5 contacts plus favorite colors plus 10 latest updates" identified as a single resource, so that the client developer can get with a single GET.
Tasks and Processes: An example is an account transfer with some back-end process to complete the transfer at the end of the business day. Some in the audience wondered if it is RESTful to identify such an account transfer "process" (something that is typically identified as a verb). But why not? Such processes can be resources themselves with their own state and lifecycle.

Explaining State in HATEOAS

2008-10-22T16:54:01Z

Explaining "state" in "Hypermedia as the Engine of Application State" (HATEOAS) is a bit tricky, particularly when you have to do it under two minutes.

The problem is that, the word "state" means different things to different people. For most of us coming from some background in web development, state usually involves numbers, strings, booleans, and other objects stored in some place, say, in an in-memory session. For instance, every beginner-level book on web development includes a shopping cart style sample that stores the cart in an in-memory session. If we extend that notion to understand or explain HATEOAS, it would make us jump to the conclusion that, to make hypermedia as the engine of application state, the server will have to encode similar objects into some XML or such form of representation in response to each request. This line of thinking is a trap.

Here is why. Once the server includes such state in a representation, the next step for the client is to replay the state in future requests to the server. Then we are talking about exchanging those objects back and forth, and not every HTTP verb has enough room to carry that state. This line of thinking will then start to shoot holes into the notion of a uniform interface because, to fit the state in a request, the client may have to resort to POST. I can almost see message passing over POST as the next logical step. At this stage, whoever is trying to explain HATEOAS may have make some lame excuses and move on. Whoever is listening will then conclude that "yeah, this won't work for my apps".

Here is an example that I find most useful to explain the "state" in HATEOAS.

There are three pages in a UI. The first page has a link to go to the second page. The second page has a link to go to the previous page as well as the third page. The third has a link to the second page and another link to the first page.

A client starts from the first page, and then through the link on that page, goes to the second page. The fact that this page has one link to the first page and another to the third page implies that the current state of the application (i.e. the interactions) is that "the client is viewing the second page". That is what it means by hypermedia as the engine of application state. It does not necessarily mean serializing application state, such as "<page>2</page>" into representations.

I admit that I am simplifying this a bit. The point is that state does not necessarily mean some data stored in representations. HATEOAS means that representations reflect the current state of the app through links with known relations. Those links may contain opaque references to some persistent state on the server.