I spent part of the weekend reading the JAX-RS 1.0 Specification. With a wife, 5 kids, a dog, and a needy mother-in-law, I'm pretty busy. AYSO soccer, youth football games, and family outings take most of weekend time, but Sunday nights are my time. Ahh, time to relax you might think. But no...I spent most of the time reading a technical spec.

I recently hinted that I was beginning to explore RESTful web services, and I'm planning to write a full-length introductory article on the topic soon. Before I go that far, I thought I might share some of my questions and comments (my annotations) of the JAX-RS 1.0 Spec.

Like a good novel, the spec deserves to be read from beginning to end. Let's start at chapter 1. OK, I'm kidding about the good novel part, but still, you should probably start at the beginning.

Chapter 1 is the intro. What did I get from it? Well, it is an introduction after all. That means that it's not particularly heavy on details, but it does set your expectations for what the spec will define. The specification defines the Java APIs that allow you to create web services based on Representational State Transfer (REST) architecture.

What's REST architecture? You can do a lot of reading to finally figure this out. In a very, very small nutshell...REST designs for web services define resources exposed as URIs. You operate on those resources using the basic HTTP vocabulary of GET, PUT, POST, DELETE, maybe a couple other HTTP actions. To be REST based, a web service must expose resources as URIs and allow applications to access those APIs through the standard HTTP actions. Actions and methods do not go into the URI path or query string.

Goals. The spec wastes no time letting you know just what its intentions are. You have to have goals, so here they are:

• POJO based. You can annotate plain ol' Java objects to create web resources.
• HTTP centric. HTTP is the fundamental network protocol. Nothing more complex should ever be needed for a web service.
• Format independence. My take on this is that the API will let me consume and produce a variety of MIME types in entity bodies. I wasn't exactly certain what was meant by "entity bodies", but I'm going to assume the spec is talking about the payload/data portion of an HTTP request or response.
• Container independence. Hmmm... I suppose this means I'll be able to use the API in standalone Java SE applications, any web-tier app server, or even a simple servlet/jsp container. the spec promises to define how to deploy a REST web service into a servlet environment.
• Inclusion in Java EE. The spec promises to show me how to deploy a service into a full-blown Java EE stack...a full app server like Weblogic or Glassfish perhaps? I'll find out I suppose if I keep reading.

Non-Goals. I always get a kick out of "non-goals". This is the section that tells you what the spec will not specify. I dunno. That's funny to me. I suppose its a way of letting readers know right away that certain subjects won't show up later in the specification. And if you wonder whether a missed subject is an oversight, you can always check the "non-goals" section. I guess if the missed subject is in the non-goals section, you can be sure that the subject was considered but left out intentionally. If something is not specified entirely and is not in the non-goals section, can we assume that point is an unintended oversight?

• No support for any Java platform before Java SE 5. Eh, ok. No big deal for me.
• Description, registration, and discovery. Maybe this means that the authors don't spec out how to advertise the service in JNDI or LDAP or UDDI? OK, again no big deal there.
• Client API. I see. The spec isn't going to tell me how to write a client that uses the service. Hmmm. I suppose that's fine. The whole point of a RESTful service is that it's accessible from any HTTP client. I suppose the authors could make that clearer and just move on from there.
• Data model/format classes. The spec doesn't really say much about what that means. No wonder...this is the non-goals section. LOL. But seriously, I think this means the spec isn't going to provide specific handlers for all the various MIME entity bodies in a request or response. However, the specification will allow applications to define its own entity handlers. I hope that's what the spec authors mean.

Terms. My only complaint about the terms section is that it immediately references later parts of the spec. Ugh. Forward references to material I haven't read yet doesn't help me much at this point.

• Resource class. A resource is something exposed by your web service. Maybe a name, book, a photograph...anything really.
• Root resource class. The spec says that "root resource classes provide the roots for the resource class tree." Hey, isn't that a circular definition? Here's what I get from it. A root resource is a resource that provides other resources. I'm sticking with that until the spec clears things up.
• Request method designator. Another forward reference to something called a resource method. Good thing that term is next in the list. It turns out that a request method designator is an annotation you can put on methods in a resource class. These annotated methods will be the handlers for HTTP GET, PUT, POST, and DELETE requests on a resource.
• Resource method. A resource class method that has a request method designator. So, if I have a getBook method, I might annotate it with @GET, and that would make it a resource method...it handles GET requests for a book. I'm starting to get the idea that annotations play a big part of the spec.
• Sub-resource locator and sub-resource method. These sound a lot alike. The term definitions are not particularly helpful here, and they refer me to a later section that apparently will clear things up. The specification terms say that a sub-resource locator is a resource class method that will help me "locate" a sub-resource. A sub-resource method is a resource class that will "handle" a sub-resource. Nice. Hey, what's the the difference between "locate" and "handle"? I'll have to wait until section 3.4.1 to find out. OK. I'll wait.
• Provider. An implementation of a JAX-RS extension. Here we have another forward reference, this time to chapter 4. Uncool, but I'll live with it. Seriously, though, some kind of example would be helpful here.

Whew...that's it for chapter 1. We had some goals, non-goals, and some terms. And well, I'd say I'd rate the sections in this same order. The goals section is the most informative, the non-goals is helpful I suppose to know just what will NOT be described, and the terms are just frustrating. The frustration comes from the referal to later sections. I suppose that can't be helped, but it's still frustrating from a newbie perspective.

Chapter 2 is about applications...supposedly. At two pages long...really just one after you throw out the headings...this chapter doesn't contain much.

Here's what you'll get from chapter 2 (Applications):

• Your application will define an Application subclass. This subclass locates resource and provider classes that will be used in the web service.
• You'll be able to publish your web-service in a variety of containers, including vanilla Java SE environments and servlet environments. For JavaSE, you'll use RuntimeDelegate#createEndpoint. For servlets, the spec just says that we'll need to define a servlet that is a subclass of Application

And that's it for chapter 2...really.

Have you read the spec. If so, do you have any notes that clarify or help us understand either of these first two chapters?