It often pains me to hear people talking about  so-called “RESTful URLs”. If you’re using that term, or your spending the majority of you application planning designing URI structures rather than your media types, then chances are you don’t really get the concepts in REST.

Frequently, I see developers sit down and start doodling a “REST API” by mapping out a bunch of URI templates like so:

/users/{userId}

/users/{userId}/stuff

/users/{userId}/stuff/{stuffId}

I’ll admit that I’ve been guilty of taking this approach myself. For one thing, it’s easy to communicate on paper. Most folks in business roles are used to seeing site maps where the content layout and URL structure are usually one in the same. By laying URI templates, you’ve kind of accomplished the same thing. Folks can visualize a high-level structure of your application, but you end up backing yourself into a corner that is difficult to get out of. Stu Charlton perhaps summed it up best in one of his more insightful posts:

If one is thinking of “how to methods map to my URI structures”, we’ve basically lost the plot as to why we have HTTP, URIs and media types in the first place. The goal is to *eliminate* the API as we normally think of it. (It’s not about a library of calls over a network).

The problem is that in approaching application design with the URI structure first is that you’re doing things bassackwards. Some people do this because they’ve followed some debatable advice and identified all of the “nouns” their application and started to work out a series of URL patterns that map to these nouns. As they create these URLs, they’ve followed some questionable advice as to what constitutes a “RESTful URL.” Subbu has another nice post dispelling some of those claims, so I won’t get into it here. The problem with doing all of the URI structure work up front is that you end up create a set of type resource URLs end up becoming fixed. Clients now end up coding to a specific set of URI patterns and/or conventions that are only discoverable from your documentation. The URI says nothing about what the data looks like or how the client should interpret it.

Imagine for a moment that you’re a DBA and you’re designing a set of database tables. Which of the two activities are you likely to spend more time on:

1. The structure of your primary keys
2. The schema of your database tables

A few of us would opt for something like MySQL’s auto-increment function and we’d be spending the majority of our time on describing the schema. In designing a RESTful application, you should be focusing on the design of your media types rather than what your URLs look like. To be more blunt: you must be focusing your efforts on what the hell your data looks like to consumers of your application. In addition to that, you need to think about how you are expressing links to other resources within your application or resources that are external to it.

This isn’t to say that URL design should be arbitrary and delegated to your web framework of choice. Of course not, you should still have URI strategy. The point is that the specific URI structures are not what consumers of your API will have to deal with directly. It is bad form to make a client rely on “out-of-band” information to construct a URI in your own special little way in order to get into your application. Take this blog post for example. You likely followed a link posted somewhere else. It could have been from an Atom feed, a search result in Google, or a Bit.ly link off of Twitter. It is highly unlikely that you had to type in the URL yourself and figured out the WordPress permalink structure that I have enabled on this site. If you did do that, well then, you’re awesome!

The fact is that clients will enter your application from some entry point or bookmark you’ve defined (.well-known is looking promising), or somewhere else on the web. Unless you’re a major player like Amazon, Facebook, or others, these clients won’t know that you have documentation that painfully detail your APIs URI structures. These clients will simply follow a link into your application. They didn’t type it in according to your fancy-schmancy URI template scheme that is only found in your documentation.  The URL is only a means to identify an locate a resource on the web, it does not define how the resource is represented or make suggestions as to what it’s about (remember that URIs are opaque?). At the end of the day, the client is going to have to be able to understand the media type that is retuned by requests made that URI. If you spend all of your time up front mapping methods to URI structures, you’ll end up introducing a coupling that you can’t easily break free from.