Appendix A
Some characters cannot be part of a URL (for example, the space) and some other characters have a special meaning in a URL (for example, the character = is used to separate a name from a value). The URI generic syntax uses URL encoding to deal with this problem.
It is recommended you use your platform's normal URL building libraries to automatically encode parts in your URLs (the filters and values), to ensure the URLs are properly escaped for your platform.
\nImportance of URL encoding
\nURL encoding is required to convert special characters because:
\n– Have special meaning in some contexts
\n– Are not valid character for an URL
\n– Could be altered during transfer
\nSafe and unsafe characters
\nBased on Web Standards, the following quick reference chart explains which characters are “safe” and which characters should be encoded in URLs.
\n| Classification | \nIncluded Characters | \nEncoding Required | \n
|---|---|---|
| Safe characters | \nAlphanumeric [0-9a-zA-Z], special characters $-_.!*'(), and reserved characters used for their reserved purposes (e.g., question mark used to denote a query string) | \n NO | \n
| ASCII Control characters | \nIncludes the ISO-8859-1 (ISO-Latin) character ranges 00-1F hex (0-31 decimal) and 7F (127 decimal) | \nYES | \n
| Non-ASCII characters | \nIncludes the entire “top half” of the ISO-Latin set 80-FF hex (128-255 decimal.) | \nYES | \n\t\t
| Reserved characters | \n$ & + , / : ; = ? @ (not including blank space) | \n YES* | \n
| Unsafe characters | \nIncludes the blank/empty space and \" < > # % { } | \\ ^ ~ [ ] ` | \n YES | \n
* Note: Reserved characters only need encoding when not used for their defined, reserved purposes.
\nExample of encoding
\nYour platform's normal URL building libraries will automatically encode parts in your URLs. Any unsafe or unprintable characters that will be provided as filters and values will be replaced with a percent sign (%), followed by the hexadecimal digits that correspond to the character's value.
\nSome common characters that must be encoded are:
\n| Unsafe character | \nEncoded value | \n
|---|---|
| = | \n%3d | \n
| + | \n%2b | \n
| & | \n%26 | \n\t\t
| # | \n%23 | \n
| \" | \n%22 | \n
| < | \n%3C | \n
| > | \n%3E | \n
| % | \n%25 | \n
| | | \n%7C | \n
Consider the example where a filter is supplied in a URL and filter value has a special character in it. For example, a user may enter an email address as \"joe&user,main\"@example.org . In this example, double quote and & need to be handled specially, otherwise it may not be interpreted correctly.
http://host.server:port/api/reporting/v0.1.0/users?filter[_useremailaddress]=[\"joe&user,main\"@example.org]http://host.server:port/api/reporting/v0.1.0/users?filter%5b_useremailaddress%5d%3d%5b%22joe%26user%2cmain%22%40example.org%5d