Handy URI Templates 2.0.1 is out

After a months of not blogging and kind of working on my URI Template library, I finally managed to get out version 2.0.1. The new API makes a quite a bit of changes and it does break some things in version 1.x. Here’s a run down of what has changed:

  • Better error handling. The API can now be more specific about what the error was and more importantly, where it was.
  • The code was refractored to support and internal model, which will help support reverse matching.
  • A new UriTemplateBuilder API for programatically creating URI templates
  • Support for Jackson serializer/deserializers

Overall, it’s cleaner and easier on the eyes. Now to wrap up reverse matching.

Handy-URI-Templates 1.1.7 Released

Yesterday Handy URI Templates 1.1.7 was released which fixed a few uritemplate-test issues as well as some URI encoding fixes. Hat tip to tekener for those fixes.

With that out of the way, I’ll be focusing on 1.2 which will change the API a bit, but will finally add reverse mapping so that you can use it to match request URLs to a URI template pattern. It turns out that this is a bit more complicated than I first imagined. A number of folks have pointed to the excellent wo-furi project as this already does reverse mapping. However, it only handles level 1, and maybe level 2 templates. Things get hairy when you start reverse mapping level 3 and level 4 templates.

Handy Aspects Moved to GitHub

A few years back, I dabbled a bit with Aspect Oriented Programming and dorked around with JBoss AOP and AspectJ. I created a few aspects an threw them up on Java.net. Over the years, I never really kept up with maintaing the project. Since then, Java.net migrated projects and Handy Aspects was removed. Since then, I have received a few requests for the code and I planned on moving it to GitHub.

But rather than simply throwing the code up there “as-is”, I decided to bring the project up to date a bit. For example, I moved the build from Ant to Maven and brought the dependencies up to the latest versions. I also removed JBoss AOP version and everything is now based on AspectJ. With that said, you can follow and fork the new project Handy-Apsects project here.

I want to like SCXML, but executable XML is a bit of a two-bagger

Over the past few days I have been reading up on the State Chart XML spec. Ever since reading some of Stu Charltons ideas on a RESTful Hypermedia Agent and listening to his WS-REST keynote presentation, I’ve taken more of an interest in hierarchical state machines and began taking a more in-depth look into SCXML.

The design of SCXML is interesting. I like the ECMA Script functionality and XML structure feels clean at first. It all seems fine until you get to the section on executable content. There’s a bit of debate around “executable xml” and executable XML frameworks like Jelly. And even folks poking fun at the idea of an XML programming language. As a Java guy, I have grown to dislike build tools such as Ant due to the fact that one can express relatively complex conditional logic in XML. I like tools like Maven better since it’s XML model is more declarative rather than executable (profiles are conditional). When I need more complex build operations, I’d be looking at tools like Gradle. Don’t get me started on XSLT.

I really like the concept of SCXML, but I’m not sold on the design. I don’t really have issue with the use of XML in general, I get it. However, the executable XML content bit is really hard to get past. Expecially when a scripting evironment is available to the SCXML environment. I can debug JavaScript code with a number of tools. Executable XML content? Not so much. For me, the executable content bit is the technical equivalent of a two-bagger.

Handy URI Templates 1.1.2 Released

After a few weeks of tweaking, I put out a new release of Handy URI Templates. What’s important about version 1.1.2 is that it is now being tested against the uritemplate-test suite started by Mark Nottingham. Most importantly, it is also now passing all tests. Additionally, this release also marks the introduction of expression validation as well. If you’ve been using the 1.0.x versions, I’d highly recommend moving up to 1.1.2.

Fun with URI Templates and the Facebook Graph API

URI Templates can make interacting with the web APIs like the Facebook Graph API a little easier. Here, I’ll show you how you can use URI Templates to create request URIs into the Facebook Graph API using the Handy URI Templates library. The URI Template examples described should be usable by any RFC6570 URI Template processor, but I’ll be focusing on how to use the Handy URI Templates API in Java. If you’re using PHP, have a look at Michael Dowling’s excellent Guzzle Framework which has great URI template support.

URI Template Basics

We’ll assume you have some familiarity with URI templates. Basically, a URI template is expression where replacement variables are identified by the text between ‘{‘ and ‘}’, like so:


Where {id} is the name of the variable. This is similar to how paths are expressed in JAX-RS, and OpenSearch URL template syntax . The RFC6570 spec provides a lot more details on the URI template standard syntax, so we’ll focus on how to use URI templates in conjunction with the Facebook Graph API.

Facebook Graph API Basics

For the most part, most URIs in the Graph API follow the basic pattern of hostname + id. In a URI template, this pattern can be expresed as:


When the template variable is expanded, it will allow you to create URIs that can be used request resources like so:

And so on. Facebook also requires you to supply the access_token in a query parameter on the request URI, so now we end up with the expression:


Please check the Facebook documenation on how to get the token.

Using the Handy URI Templates API, you can create a URI from an expression like so:

String expression = "https://graph.facebook.com/{id}{?access_token}";
String uri  = 
              .set("id", "bgolub")
              .set("access_token", System.getProperty("fb.access_token"))

This will give you the following URI:


Because the {id} variable can contain sub paths, we need a way to express that. If we have want to express a URI template that gets a users information or the users photo albums, we need additional path segements. We could use multiple path segments with more variables, but this can make the template more complicated. One option is to modify the expression so that {id} can accomodate a single path segement or multiple path segments by rewriting the expression as:


This does a few things:

  • By putting the path ‘/’ operator in the variable expression, we’re stating that the values in this variable path segements. By default, if the variable values is an array, Collection or Map, the values will be ‘,’ delimited.
  • The * modifier means ‘explode’. With an array or Collection plus the explode modifier, the values will be delimited by the ‘/’ operator.

Now if we change the code a little bit:

String expression = "https://graph.facebook.com{/id*}{?access_token}";
String uri =  
               .set("id", new String[] {"bgolub","albums"})
               .set("access_token", System.getProperty("fb.access_token"))

You’ll note that the value we pass to the id variable is an array of strings and the processor will render valuse as two strings separated by a /.The resulting URI is now:


Now lets see how we can make more advanced types of requests.

More Advanced Requests

The Graph API has a number of query parameters that modifiy the request. All of these are defined in the Facebook Graph API documenation so I won’t detail them here. With all of the query parameters collected, you end up with the following URI template expression:


You can pretty much use this template express for the majority, if not all, of the Facebook Graph API. We’ll use that expression for rest of the examples.

Search Request URIs

With the URI template, we can create URIs that map to Graph API search requests. Using the “coffe” example from the Facebook documenation:

String expression = "https://graph.facebook.com{/id*}{?q,ids,fields,type,center,distance,limit,offset,until,since,access_token}";

String uri = 
                .set("q", "coffee")
                .set("center", new float[] {37.76f,-122.427f})
                .set("distance", 1000)
                .set("limit", 5)
                .set("offset", 10)
                .set("access_token", System.getProperty("fb.access_token"))

This will give us the URI:


Note how the variables until and since are not included in the expanded URI.

FQL Request URIs

Even things URIs with FQL queries can be expressed in a template. Give our code:

String expression = "https://graph.facebook.com{/id*}{?q,ids,fields,type,center,distance,limit,offset,until,since,access_token}";

  String uri = 
               .set("q", "SELECT uid2 FROM friend WHERE uid1=me()")
               .set("access_token", System.getProperty("fb.access_token"))

Wrap Up

Hopefully this gives you a good idea on both how to use URI Templates in general, and a good insight into how you can use teh Handy URI Templates API. If you want more exmaples, have a look at the code on GitHub here. There are examples for Facebook, Twitter, and GitHub.

A URI Templates Implementation for Java

In my copious spare time, I have managed to cobble together an initial implementation of the URI Templates spec (RFC6570),  for Java. The project is up on GitHub here:


The majority of the documentation is available in the README file, so have a gander at that for details on how to use it. It’s in the initial phases right now, but it’s a good time to kick the tires and provide feedback.