Sometimes, you can let things slide, but there are other time when terms are just used so incorrectly that it has to be called out. One thing that always gets me is the gross misuse of the term REST. For those who know what REpresentation State Transfer (REST) means then you know that, although the REST architectural style is commonly used with HTTP, it is not bound to any specific protocol.

One of the things that starts my head spinning is seeing how the term “REST” is so often used in place of thing they really mean in order to toss out buzzwords. When I’m involved in technical discussions or read articles on the web, I start to feel like Inigo Montoya when I hear the term “REST”. More often than not, someone is probably referring about HTTP, or even HTTPS, but you can never be too sure. Here’s a few of my favorite statements:

We’ll send it over REST

Oh no you won’t! Given that REST is not a protocol, I find this kind of statement simply mind boggling. One can assume that someone would like to return data over HTTP. However, it is entirely possible to create a RESTful application over other protocols such as XMPP, RMI, or something else. It helps top be specific when you’re involved in a technical discussion.

We’ll make a REST request

Are you sure? What exactly does a REST request look like? If you can’t request data from a URI like rest://example.com/foo, then you’re not making a “REST request.” As stated above, be specific as to what protocol you’re using.

We’ll return it as a REST object

This one pains me more than the other two. Seriously, what kind of “objects” are RESTful? Is is XML, JSON, binary, what? Again, there is no such thing. There are only resources and representations, and it’s the representations of those resources you need to be specific about. What, exactly, are you sending over the wire?

We’ll just add some methods to our REST server

OMFG! For real, a REST server? Even though the Facebook claims to have one of those, it doesn’t make improper use of term valid. You can’t serve “REST,” plain and simple.

Just so that I can continue beating the horse: you can’t send jack over REST. REST is not HTTP and HTTP is not REST. If you have a web API that you’re exposing over HTTP in a RESTful fashion, why can’t it just be called an HTTP Service or API server? Correct use of the term REST is just as important as implementing a RESTful application correctly. Sadly, the same folks who use the term REST incorrectly are also not creating applications can claim to be RESTful.

Over the past few weeks, I’ve been taking a deep dive into the Semantic Web.  As some will tell you, a number of scalability and performance issues with the Semantic Frameworks have not been fully addressed. While true to some extent, there’s been a large amount of quality research out there, but it is actually somewhat difficult to find.  Part of the reason is that much of this research is published on the web in PDF. To add insult to injury, these are PDFs without associated meta data nor hyperlinks to associated research (which is not to say that prior research isn’t properly cited).

Does this seem slightly ironic? The Semantic Web is built on the hypertext-driven nature of the web. Even though PDF is a readable and relatively open format, it’s still a rather sucktastic hypertext and on-screen format (especially when it’s published as a two-column layout).  PDFs are an agnostic means of publishing a document that was authored in something like Microsoft Word or LaTex. They are generated as an afterthought and most do not take the time to properly hyperlink these PDFs to external sources. Why is this bad? Given that we’re using the document web (or rather the “Page Ranked” web) of today, this makes it a bit more challenging to locate this kind of information on the web. In a sense, this is akin to not eating your own dog food. If knowledge isn’t properly linked into the web as it works today, it effectively doesn’t exist. Guys like Roy T. Fielding get this, and it’s most likely why his dissertation is available as HTML, as well as PDF variants.

As a friendly suggestion to the Semantic Web research community: please consider using XHTML to publish your research. Or even better, XHTML with RDF/A. Additionally, leverage hyperlinks to cite related or relevant works. It’s not enough anymore to use a purely textual bibliography or footnotes. The document web needs hyperlinks.

There’s a lot of cool and important stuff being worked on but this knowledge is not being properly disseminated. No doubt, in some cases publishing to two different formats can be a lot of work. But in the long term the payoffs are that information is widely available and you’re leveraging the Semantic Web as it was meant to be.

There has been some discussion lately regarding integrating JBoss Seam with RESTEasy. Jay Balunas recently made about post on his thoughts on ths subject, so I thought I’d post some of mine. For the record, I am a huge fan of Seam and I think there’s definitely a place for Seam in RESTEasy, so here’s a few of my musing on the subject:

Seam Managed Persistence Contexts

This is a really great feature of Seam and it adds a lot of value to a framework like RESTEasy. If you have a resource that returns a entity that is a complex object graph that will be marshalled to XML, you have a high potential for hitting a LazyInitialzationException. This is especially true if you’re calling a SLSB to get your data because the marshalling process is handled on the web tier, outside of the EJB transaction. If the entity was not fully initialized, your object graph will be incomplete and you will get a LazyInitialzationException. In the initial version of RESTEasy, I used a Seam managed persistence context in order successfully marshall a complex entity using JAXB without getting a LazyInitializationException. I could have written a filter that was similar to the Spring OpenSessionInViewFilter to span the transaction over the entire HTTP request, but Seam made this problem transparently go away in very elegant manner.

Transactions/Conversations

Conversations are one feature of Seam that cause a lot of folks to raise concerns about the stateful nature of the framework in regards to REST. However, I think in some instances, some of the conversational aspects of Seam can be utilized in a RESTful design. Take this thread on the JSR-311 mailing list from Bill regarding Transactions in JAX-RS:

No, I don’t want JAX-RS to have a transaction model :)

One pattern I’ve seen in REST is how they solve distributed
transactions.  The pattern seems to be

/transactions/{tx-id}/.../whatever/your/real/resources/are

So really the transaction resource is allowed to contain any resource
the server supports.  (I hope you are following me, if not I’ll expand).

IMHO, this is something I think Seam could lend a hand with. Taking both Seam’s support for conversations and jBPM, you could conceivably use a long-running conversation to implement such a feature whereby you might end up with something like:

/transactions/{conversation-id}/.../whatever/your/real/resources/are

It’s not a fully baked idea, nor might it be quite the same thing that Bill is talking about. However, it could potentially be RESTful if implemented properly and Seam already provides the plumbing for this out of the box.

Entity Resources

The Seam framework (as in org.jboss.seam.framework), offers a lot of convenience features that make working with JPA and Hibernate a breeze. I had a silly idea a while a back about how to expose entity beans as a resource without the need for a dedicated resource class. The idea wasn’t fully baked (and in hind sight, those details are actually kinda crappy and overly verbose), but the general idea was to make it easy to navigate elements of an object graph. For example, if you were to access the following URI:

http://myhost/contacts/12345

You’d end up with the full object graph as XML for contact ID 12345. If you just wanted to look at one address for that contact, you should be able to call:

http://myhost/contacts/12345/addresses/home

And you would get just the XML element for the contact’s “home” address. What I don’t want to do is create a separate resource class for each element and each collection type in the object graph. You shouldn’t have to create a ContactsResource, ContactResource, AddressesResource, AddressResource, etc. Ideally, you should be able to have one class, or just the entity itself, that can represent the resource. I’m currently working to refine this idea for RESTEasy and much of the Seam framework API could be useful in making this a reality.

I could go on, but I think there’s a lot of value that Seam can bring to RESTEasy.

Updated (1/18/2011) : Because there’s still a lot of confusion, I’ve created a third post that attempts to resolve a lot of the questions from the comments on the last two posts. The new post is here.

Updated (8/27/2009): I’ve created another post that attempts to make the distinctions a bit more clear. The new post is here.

What is the difference between a URL and URI and why does it matter? This topic is confusing to some (myself included) and I thought I’d share my understanding of the two concepts. I’m hoping this post will give you a better understanding about how the two differ and why it matters to some.

Note: The goal of this post is to simplify the distinction between URI and URI. If you feel that in the summarization process something was lost, or it’s simply just correct, please post a comment and the information will be corrected. I only ask for any comments/criticism to be constructive.

Update: Thanks some constructive, and not-so constructive, feedback from some readers I have updated this post to correct many of my own misunderstandings. Of which, there were many.

URI

A URI identifies a resource either by location, or a name, or both. More often than not, most of us use URIs that defines a location to a resource. The fact that a URI can identify a resources by both name and location has lead to a lot of the confusion in my opionion. A URI has two specializations known as URL and URN.

URN

A URI identifies a resource by name in a given namespace but not define how the resource maybe obtained. This type of URI is called a URN. You may see URNs used in XML Schema documents to define a namespace, usually using a syntax such as:

<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            targetNamespace="urn:example"

Here the targetNamespace use a URN. It defines an identifier to the namespace, but it does not define a location.

URL

A URL is a specialization of URI that defines the network location of a specific resource. Unlike a URN, the URL defines how the resource can be obtained. We use URLs every day in the form of http://damnhandy.com, etc. But a URL doesn’t have to be an HTTP URL, it can be ftp://damnhandy.com, smb://damnhandy.com, etc.

The Difference Between Them

So what is the difference between URI and URL? It’s not as clear cut as I would like, but here’s my stab at it:

A URI is an identifier for some resource, but a URL gives you specific information as to obtain that resource. A URI is a URL and as one commenter pointed out, it is now considered incorrect to use URL when describing applications. Generally, if the URL describes both the location and name of a resource, the term to use is URI. Since this is generally the case most of us encounter everyday, URI is the correct term.

I just came across a quick article on The Server Side about a JSF framework called RESTFaces. My initial reaction was “oh cool, a JSF framework that might adhere to RESTful principals.” Sadly, there isn’t much more than HTTP GET support that is “RESTful” about RESTFaces. RESTFaces touts itself as being a

RESTfaces for JavaServerâ„¢ Faces Technology make it possible to write bookmarkable pages using JavaServerâ„¢ Faces.

In a nut shell: RESTFaces allows you to invoke actions via HTTP GET as opposed to just POST actions. JBoss Seam has a similar feature and their docs describes it as a means of making RESTFul applications that can be bookmarked. To be fair, Seam does not claim to be a full-on REST framework. Now I am a huge fan of JBoss Seam, so I don’t mean to come off as pooh-poohing that effort. But I wonder, is just providing GET support enough enough to be considered RESTful? At a low level, probably yes. But there could be so much more.

This could all change as the specifications for JSF and Web Beans matures. JSR-311 is a thriving work in progress and JSR-314 is also still getting ramped up as well. As these spec mature, some nice integration points might be:

Support for URI templates.

JSR-311 is currently defining support for this, but if this were integrated into JSF URIs would not be just bookmarkable, but also human readable. For example, instead of:

http://somehost/blog/entry.action?id=1234

You could have something a bit cleaner

http://somehost/blog/entries/1234

Your entry ID is now a component of the URI, which makes it a lot easier on the eyes. If you ever have had to deal with marketing applications, you can appreciate the value of this.

Support for multiple representations via HTTP Content Negotiation

Again this is something that JSR-311 is defining, but if this is integrated into JSF, or Web Beans for that matter, it would allow a single URI to deliver different media types. Using the example above, the same URI:

http://somehost/blog/entries/1234

Could deliver the content as a PDF, or an HTML format that is more suitable for a mobile device and the decision is made by the framework. The user would not have to execute a specific URL for each type:

http://somehost/blog/entries/1234.html
http://somehost/blog/entries/1234.pdf
http://somehost/blog/entries/1234.wml

Or worse:

http://somehost/blog/entry.action?id=1234&type=application/pdf
http://somehost/blog/entry.action?id=1234&type=text/html

Through content negotiation, the user just needs the URI and the application will take care of delivering the proper response. If you’re looking for an example of a present day implementation, look no further than Apache HTTPD. JBoss Seam already supports a number of ways to generate other media types such as PDF, charts and graphs, and other, so I think they’re in a great position to deliver this kind of functionality. On the plus side, at least these two frameworks do allow one to use HTTP GET which is a big help.

As I’m reevaluating and retooling RESTEasy, I’m thinking about what it is going to take to reach 1.0. At a high-level, RESTEasy will provide:

  • A Server side API as a JAX-RS Implementation
  • A Client API similar to what I described in this post.
  • A set of common code that is shared between client and server.

As for features, here’s the run down:

  • A complete JAX-RS implementation
  • Use EJB 3 Session beans as a RESTful end point
  • Use EJB 3 Message-Driven beans as a RESTful end point
  • Support for JPA and Hibernate
  • Integrated GZip encoding
  • An integrated HTTP proxy for Flex applications (to get around this issue)

These are the basics for the 1.0 release. Right now, I’m starting to get the code in back inline with JSR-311. If there’s something you want to see in 1.0, please let me know.

Bill Burke has just posted a bunch of really great feedback on the latest draft of the JAX-RS spec. If you haven’t had a chance to look at the spec, head over here. One thing that JSR-311 had initially chosen not to do was to define a client API. There has a been some grumblings about the lack of a client API in the spec. After readings Bill’s post, I’m starting to think there is a need for a client API in the spec.

There are a few reasons why a client API could make sense:

  • You can reuse the same collection of EntityProviders on the client. They are already handle request/response anyway, so it’s a natural choice.
  • Some of the annotations are applicable to client applications
  • Utility classes like URIBuilder are useful to both sides of the API.

One of design decisions I made with RESTEasy was to separate the framework into three parts:

  • A Client API
  • A Service API (soon to be implementing JSR-311)
  • And a collection of common code that is shared between both client and server

The RESTEasy common library handles thing like EntityProviders(aka RepresentationHandlers in the old RESTEasy), Header and Request info, and some other common utility classes.

What Bill suggested was to have the ability to place annotations on interface classes. This is what the current implementation of RESTEasy does with EJB3-based Resources. The cool thing that Bill is suggesting is that it would be then possible for the client API to do something like:

@Stateless
public class PeopleResourceBean {	
    public Person getPersonById(int id) {...}

}

Also note how the JAX-RS annotation don”t litter your bean class? :) You can then annotate your local interface such that:

@Local
@UriTemplate("/people")
public class PeopleResource { 
  @UriTemplate("{id}")
  @HttpMethod("GET")
  public Person getPersonById(@UriParam("id") int id);
}

Then finally, you’re client code could do something like:

public class PeopleServiceClient {	

@HttpResourceRef("http://somehost.com") PeopleResource peopleResource;

public Person getPersonById(int id) {
 	return peopleResource.getPersonById(id);
}

}

The client side framework would the take care of implementing the business of connecting to the remote service. The @HttpResourceRef is just an idea at this point, but this will provide a means to define the root location of the service. Once the interface is injected, it reads the @UriTemplate annotations to access the resource.

I’m starting to think this could be a pretty cool thing to have in the spec, or at the very least in RESTEasy 1.0.

I’ve found myself enjoying working with Adobe Flex. Flex does a lot of things really well, except its support of the HTTP protocol. Here’s a few things folks don’t know about the Flash Players HTTP support:

  • It only support GET and POST methods. In order to use other methods such as DELETE and PUT, you have to the proxy service in Live Cycle Data Services. Lame!
  • The Flash Player can’t read entity responses if a service returns a response code higher than 200. The LDS proxy gets around this limitation by forcing the response to a 200 status and returning the fault entity. Without LDS, there’s no way to get the response entity. Still lame.
  • You are extremely limited to the number of header values you can set. The following header values cannot be used by the URLRequestHeader class: Accept-Charset, Accept-Encoding, Accept-Ranges, Age, Allow, Allowed, Connection, Content-Length, Content-Location, Content-Range, Date, Delete, ETag, Expect, Get, Host, Keep-Alive, Last-Modified, Location, Max-Forwards, Options, Post, Proxy-Authenticate, Proxy-Authorization, Public, Put, Range, Referer, Retry-After, Server, TE, Trace, Trailer, Transfer-Encoding, Upgrade, URI, User-Agent, Vary, Via, Warning, WWW-Authenticate, x-flash-version.

These features are extremely limiting for an RIA platform. It’s not always easy to try an sell RIA solution that is based on a platform crippled by limited networking support. I sincerely hope that future incarnations can get around these issues by providing a real HTTP implementation.