It’s important to remember that REST is an architectural style and that it does not have an official standard. As such, the question on how to call a REStful web service will often arise. If the service you are calling supports more than one way of being called, then which way should you choose? The short answer is the one that works best for you, and by works best for you I don’t simply mean the one that you feel most comfortable using (although that is an important factor). For the purpose of this article, we will focus on path parameter calls and how they compare to query string parameter calls, two deceptively similar styles. There are inherent differences between path parameters and query string parameters that you should consider before choosing one over the other.
A RESTful web service should behave the same regardless of how it is called, and as long as the same input values are provided the service will return the same result values every time. So why choose one format over another?
If you are unfamiliar with path parameters, then simply put, a path parameter template is one where the parameter values are embedded in the URL path.
Path parameter example:
http://domain/resource/verb/value1/value2/value3
Query string parameter example:
http://domain/resource/verb?key1=value1&key2=value2&key3=value3
The above examples are rough, but they get the point across. Notice that in the path parameter example the variable values are embedded in the URL path, whereas in the query string parameter example the variable values are provided in the query string.
Path parameters have gained popularity as being more human readable and easier to understand as the path template lends itself to a natural progression of drilling into data resources. Some services offer path parameters specifically for this reason. The user experience can be likened to having a direct connection to the data resource and it is often useful for simple lookup services where no data transformation/refinement occurs, or is needed. Path parameters can enable a service to be called in a distinctive style and, depending on the functionality of the service being called, the path template can take on many forms.
Here are some common examples:
http://domain/resource/format/noun/verb/value
http://domain/resource/noun/value1/value2
http://domain/resource/noun/verb/value1?format=formatvalue
The above examples add the noun and format values, where the noun can help make the service request more descriptive, intuitive and easier to understand. The format value, when available, is commonly used to tell the service what type of response format to return, typically either json or xml.
This is not to say that a service that is called on using query string parameters cannot be designed to be as descriptive and intuitive as a path parameter service.
Caveats to look out for when using path parameters:
- Order matters: Unlike query string parameters, the order in which the path parameter values are given must correspond to the format dictated by the URL path. For example, if the service path dictates “/resource/format/noun/verb/value” then you cannot interchange it with “/resource/verb/format/value/noun/”.
- Path parameter values cannot be omitted: Unlike query string parameters you cannot omit a value in path parameters because doing so would mean changing the URL path. The only exception is the final parameter value in the URL path. If the path format is “/resource/verb/value1/value2/value3”, and you want to omit value1 then “/resource/verb//value2/value3” will not work because it is the same as “/resource/verb/value1/value2/”. In which case, you have inadvertently omitted value3. If you omit enough values then you will end up with a malformed URL.
- Reserved HTTP characters: such as “:”, “/”, “?”, “#”, “[“, “]” and “@” – These characters and others are “reserved” in the HTTP protocol to have “special” meaning in the implementation syntax so that they are distinguishable to other data in the URL. If a variable value within the path contains one or more of these reserved characters then it will break the path and generate a malformed request. You can workaround reserved characters in query string parameters by URL encoding them or sometimes by double escaping them, but you cannot in path parameters.
These are just some simple examples of how a path parameter URL request can differ from a query string parameter request. Overall, it is important to note that regardless of where the parameter variable values are placed, either in the path or in the query string, both styles must conform to the HTTP protocol. For some services, path parameters offer a more descriptive and distinct style that enforce a specific way of querying resources, whereas old-fashioned query string parameters offer greater flexibility and ease of use at the cost of being potentially less descriptive and intuitive.
