A recent post on the Dropbox developer’s blog post talked about the challenges of constructing URLs due to the challenges of encoding parameters. They proposed the idea of using encoded JSON to embed parameters in URLs. I believe URI Templates offer a much easier and cleaner way to address this issue. This blog post shows how.
Solving Dropbox’s URL Problems
Picky About Punctuation
The first example introduced the problem of spaces in URLs,?
It is true that spaces are not allowed in URLs, however, interestingly, the plus sign used in this example is not the correct way to deal with spaces according to RFC 3986, the URI specification. Web browsers allow you to use the plus sign as a replacement for space in the address bar, however, technically spaces should be encoded as %20.
Using a URI Template library you are able to clearly distinguish which parts of the final URL are literals and syntax and which parts are parameters. The parameters are considered “data” and therefore any characters that have special meaning in a URI will automatically be escaped.?
In the above example, the space in the folder parameters and the query parameters are automatically escaped.
The next example given in the Dropbox post highlights the challenges of using parameter data that contains characters that are considered URL delimiters and are therefore considered reserved.?
The example is a bit misleading because the hypen character is not a reserved character, therefore, doesn’t need to be escaped. However, the point remains that a forward slash in a parameter value should be escaped to prevent it from being considered a delimiter.
This ambiguity is easily avoided in URI Templates because parameter values are specified explicitly.?
Does the next Dropbox example demonstrate that there is some flexibility in the way you can represent lists of values in URLs.?
The problem with flexibility that is given to API producers, is that API consumers have to deal with additional complexity. Fortunately, URI Templates allows these different approaches to be handled by adding one additional character to the URI Template.?
The only difference between the two templates is the asterisk at the end of the parameter token. This is called the “explode modifier”. The additional bonus for hypermedia-driven APIs that provide the templates to the client, is the client code can be completely ignorant of which approach is being used and the server can change its mind at some point in the future and nothing breaks.
Does the next example show the technique developers use for including nested data as part of query string parameters?
Because of the clear separation between parameters and URI Templates, it makes this scenario fairly trivial. Also, considering the potentially dynamic nature of this type of query string parameters, another feature of URI Templates can be used to make this type of URL even easier to construct.?
Query string parameter names are passed through the URI Template to the URL, untouched, which is why the square brackets are not escaped. According to RFC 3986, they should be escaped. However, it is fairly common to see them in URLs unescaped. Although it is a violation of the rules, the impact is minimal because square brackets are currently only used in the hostname for specifying IPV6 addresses.
The key to URI Templates being able to help in URL encoding is that it is obvious which pieces are data and which pieces are URL syntax. This allows the encoding to only be performed where it is needed, on the data.
Personally, I do not think we need to resort to such extreme measures as JSON encoding parameters to make it easy for developers to safely construct URLs. Hopefully, this post will convince a few other people.