RFC 5545

iCalendar is now an IETF Proposed Standards Protocol (superseedes RFC 2445). Does anyone know whether this is just fixing things or whether there are additional semantics that increase the expressiveness?

Hypermedia Context

Descriptions of REST interfaces often use the notion of types when talking about the exposed resources. The Atom Publishing Protocol for example includes a section that provides a resource classification. Such classifications are not against the RESTfulness of an interface as long as the classes are expressed in terms of the knowledge a client has acquired about a resource. The Atom Publishing Protocol for example states that "a Resource whose IRI is listed in a Collection is called a Member Resource". This is a valid classification from the point of view of its RESTfulness.

In order to emphasize that such classification can only be done in terms of the acquired application state of the client I suggest the term "hypermedia context" instead of "classification". REST interface descriptions could then for example state: "The hypermedia context of a resource is called Member if its URI is listed in a collection". There is probably also value in distinguishing the client-acquired knowledge about a resource from the context used in the specification by calling the former acquired hypermedia context or just hypermedia context and the latter named hypermedia context.

I can also see possibilities to formalize hypermedia contexts along the lines of predicates, for example as an AND combination of known links, appearance of links in received hypermedia and (XPath-)matches on the representations of resources.

But I'll address that in a follow up.

Location Header Semantics

Depending on the response's HTTP status the Location header has slightly different impact on the client's application state. The following table summarizes what I extracted from the HTTP spec.

Status	Semantic	Comment
201 Created	URI of created resource	Client is notified that a new resource has been created an can dereference the URI to see what has been created, e.g. to verify its expectations. ETag can be used to provide current ETag of created resource
204 No Content	URI of created resource(?)	Clarification pending
300 Multiple Choices	URI of server's preferred variant
301 Moved Permanently	New permanent URI
302 Found	Temporay URI to use for requests to the intended resource
303 See Other	Response to the POST request is found at another URI	If client follows redirect and if the client already knows the target resource the 303 works as a notification that the previous POST has changed the target resource.
305 Use Proxy	URI of proxy to use for the request.
307 Moved Temporarily	Temporary URI to use for requests to this resource.

201 and 303 provide the grounds for interesting generic client behavior. About the nature of 305 I am not sure yet but the server's ability to redirect a client to an intermediary smells interesting.

REST Interface Implementation Design

It occurred to me today that there is a subtle design artifact that sits in between the specification of a REST API and its actual implementation. Let me try to explain what I mean:

The specification of a REST API consists of the media types, extensions and link semantics that a potential client must understand to be able to meaningfully interact with the API. The combination of Atom and the Atom Publishing Protocol is a good example of this.

The implementation of a REST API maps the 'back end layer' to a number of resources that provide access to the 'back end layer' in terms of the semantics of the REST API.

This looks like the expected differentiation between interface and implementation, much like you implement an OO interface with a class.

Interestingly, in the case of REST there is a third design artifact that resides somewhere in the middle between interface and implementation: the design decision of what resource are actually exposed and which of the interface semantics are actually used in which circumstances. It could be argued that this decision is part of the implementation, but by distinguishing the two it becomes clearer that there are many potential ways how different systems can manifest a given REST interface.

A class that implements an OO interface will always just implement the methods that constitute the interface, no decisions besides the actual implementation, no surprises. When implementing an Atom Publishing Protocol service, there is an unlimited number of ways to organize feeds and add links to feed or entry documents. One can even build two entirely different APP facades around a given back end but still use the same code to map back end resources (general sense) to feed and entry documents.

When REST API specifications define what resources a client will find on the server side and what type they have then this is an indication that the specification (wrongly) includes the server-side design artifact described above. Such specification elements must be removed from the API to make it RESTful.

Parameters are Link Relation Specific

I used to view REST APIs to be constituted by media types, extensions, link relations and parameters (query-, form- and URI template parameters). Reading through Roy's checklist again today I realized that he suggests a superior approach: By making the parameters link relation specific the problem that parameters are usually not bound to a name space goes away and there is one less class of design artifacts.