A core tenant of the RESTful API development doctrine is that a Uniform Resource Locator, as the name implies, should uniquely identify a resource on the server.
Sadly, that simple concept is often misconstrued. While the URL path component is what should point directly at the server-side resource, many well-meaning developers fall into the trap of the RESTful parameters antipattern.
RESTful parameters for path, query
RESTful API developers should be concerned with the two main parts of a URL: the path and the query.
Location of RESTful parameter elements of a URL
The path follows the domain name and should be used to coarsely identify the server-side resource that you want to access. RESTful query parameters should be used to further refine the URL. A well-formed RESTful URL should look something like this:
It's pretty clear from this example that the resource in question is the book Ulysses and it is located in a Toronto library. This is a well-designed web service API that conforms with RESTful path and query parameter best practices.
Let's compare the aforementioned URL to the following one:
www.mcnz.com/library/toronto/book/ulysses
This second URL conveys the exact same information as the first -- namely, that the resource in question is a book named Ulysses at a Toronto library. Furthermore, any REST-based framework, such as Spring Boot or Eclipse MicroProfile, would be able to understand the information packed into this URL.
The URL is indeed functional, but it implements the RESTful path parameter antipattern. The first RESTful URL example is a best practice, while the second is not.
Best practices for query REST parameters
The RESTful path parameter enables a developer to pack every bit of information necessary to identify a resource on a server but also creates an incredibly rigid design.
A tome of instructions should not be required in order to utilize a RESTful API.
Cameron McKenzie
For example, imagine a scenario where a client could go to any city to find the book Ulysses. With RESTful query parameters, the path remains unchanged, and the reference to the location is simply removed.
www.mcnz.com/library/book?title=ulysses
A developer who needed to implement this scenario through the exclusive use of path parameters, however, would face more of a challenge. What would replace the path portion of the URL that previously referenced the city of Toronto?
www.mcnz.com/library/???/book/ulysses
One approach to solve this problem might be to put a placeholder value -- such as the word any -- where the city name previously went. This option would work, but it creates its own set of problems.
www.mcnz.com/library/any/book/ulysses
Why is this RESTful parameter approach to paths problematic?
First, it wouldn't be obvious for a client to implement a special identifier, such as any in the URL. A special term to simulate a global search would need to be communicated to other RESTful API users.
Furthermore, as similarly built APIs proliferate, the number of special identifiers will also expand. If a high volume of instructions are needed to reap the benefits of a RESTful API, then the simplicity and self-explanatory nature of these APIs is lost.
The RESTful path parameter antipattern
Another option to solve this issue might be to completely remove the second parameter in the URL to indicate that no specific library will be searched:
www.mcnz.com/library/book/ulysses
Unfortunately, this approach doesn't integrate well with the most popular RESTful API development frameworks. Both the Spring and Java Platform, Enterprise Edition frameworks expect the purpose of each element in the path to remain unchanged.
If the second path parameter represents a city or a location, it should always represent a city or location. A change like this of an indexed parameter on the fly won't be supported by most RESTful API frameworks.
Properties as path parameters
Developers can also fall into a similar trap with a RESTful API design that embeds properties and attributes into the path. For example, let's say there are different translations of Ulysses available, and a query needs to be made for a Spanish edition. A path-based answer to this problem might look like this:
www.mcnz.com/library/any/book/ulysses/spanish
On first blush, this approach appears to work fine. But, as soon as a second property -- unrelated to the book's language -- is introduced, the structure breaks down.
If a user wanted to find a Spanish edition of Ulysses in paperback, how would the RESTful path parameters need to be configured? Both of the following URLs would work, but is one of them more correct than the other? Is one path more obvious or logical to the end user?
RESTful parameters for paths, queries come together
In this situation, there really is no correct answer. The only way I can see to solve the problem is simply not to use path parameters to solve these types of issues. The proper approach would be to use a combination of RESTful path parameters and query parameters together:
Combined RESTful query and path parameters make it easy to create a flexible and extensible web service that's easy to use, easy to understand and easy to integrate, which is exactly what developers want from their APIs.
Master the tenets of RESTful web service design
If you want to learn how to develop RESTful web services and, at the same time, confirm you comply with best practices and avoid RESTful antipatterns, check out the following articles, tutorials and resources:
