Effective Naming Strategies for RESTful Web Services
New descriptive languages like WADL and WSDL 2.0 are making it possible to describe the RESTful contract to client applications. However, if your RESTful web services are not named effectively, the mechanism for describing the interface may run out of steam.
One of the major shortcomings of RESTful web service design is the historic lack of any strong technology that can be used to effectively describe the service contract interface between the server and the client. RESTful APIs are flexible, sensible and provide for a great deal of loose coupling, but if an application architect is looking for an effective way to describe the RESTful API in a manner similar to the way WSDL describes traditional SOAP based web services, well the architect is sadly out of luck.
Fortunately, the description languages are catching up with the popularity of REST, and WSDL 2.0 and WADL are two technologies that are filling the RESTful need. Of course, these specifications are not perfect, as their ability to describe JSON strings and complex attributes is still lacking, but nevertheless, progress is being made.
One caveat to using these technologies, especially if software engineers are hoping to use code generators to create WADL and WSDL files is the fact that resource elements in a RESTful URL need to be separated with constants. It's actually a good idea in general, as it makes URLs more meaningful and easier to read. But new standards are making the use of interjected constants less about what's good, and more about what's required.
When you see an example, it's fairly easy to comprehend. Take a look at the following URL that might be used for a product rating service:
http://www.example.com/services/ratings/plunger/5
In this example, you can see quite clearly that a plunger is being given a five out of five product rating. But the URL is not separated with constants, which causes problems with the description languages. Fortunately, solving the problem is easy, as you can see from the following, corrected URL:
http://www.example.com/services/ratings/product/plunger/rating/5
The words product and rating are constants in the URL, and assign meaning to the corresponding resource values. As you can see, it's not a big change in terms of URL design, but it is significant, as it will make your RESTful APIs more compatible with the various description languages on the market today, and in turn, clients will have fewer problems when interacting with them.
