va-json-tools.uri-template.0.10.source-code.overview.html Maven / Gradle / Ivy
URI templates: generate URIs for your REST APIs
Why URI templates
The more time goes, the more you hear about so-called "REST APIs"; and these
REST APIs, ultimately, are nothing but URIs (or URLs if you prefer) with a
meaning.
Even before REST became all the craze, it was not uncommon, for instance, to
have personal pages accessible via http://the.site/~theuser or the like.
URI Template is an RFC which
defines a templating language for implementations to use to replace placeholders
with correctly encoded values. For instance, were you to make the URI above
parameterizable according to the username, you could write a template as:
http://the.site/~{username}
A URI template engine (such as this one) would then be able, given a valid
definition for the username
variable, to transform this template into a URI -- even if your username were to
have accentuated characters.
Why {@link java.net.URLEncoder}'s .encode() doesn't work
It does not work because its intent is not to encode strings for use in URIs
but in POST data (ie, aplication/x-www-form-urlencoded)!
Encoding for this type of data is not the same as it is for URIs; the most
obvious example of it is the space, which this method encodes as a + whereas this character is illegal in a
URI (except in the fragment part).
Sample usage
Please see the project page
for sample API usage.