URI’s, URL’s, and Special Characters [VC 21.3.1 GEN]
File paths
There are a number of characters that have special uses in various file systems.
Characters not allowed in path segments (directory names, file names)
-
U+0000 - U+001F (including TAB, CR, NL)
-
U+002F (
/) -
U+005C (
\)
While technically possible to use in path segments on various file systems, it is not possible to use these characters in Vidispine path names.
Characters not supported on certain platforms
-
U+007F ( DEL )
-
U+003F (
?) -
U+002A (
*) -
U+0024 (
$) -
U+003A (
:) -
Paths that are MS-DOS device names (
LPT1, etc) -
U+D800 - U+10FFFF
These characters may or may not work, depending on operating system and Java version. It is strongly suggested that they are not used.
API calls
In calls to the Vidispine API, the following rules apply:
-
Path segments are encoded using RFC3986.
-
Non-ASCII characters are encoded in UTF-8, and do not have to be percent encoded.
-
Percent encoding. Particularly space is encoded as %20 (not +, so Java’s URLEncoder is not the right tool!)
-
-
Non-ASCII characters are encoded in UTF-8, and do not have to be percent encoded
-
Percent encoding. Particularly space is encoded as %20 (not +, so Java’s URLEncoder is not the right tool!)
-
Query parameter values are encoded using RFC2396
-
Non-ASCII characters need to be percent encoded.
-
Space can be encoded as + (or %20).
-
-
Non-ASCII characters need to be percent encoded
-
Space can be encoded as + (or %20)
-
URIs in XML documents need to be quoted according to XML, e.g. & for &.
As a consequence, path that are used as query parameters (e.g. the URL parameter in imports), need first to be encoded as a URI, then encoded as a URL query parameter.
Example 1
Path: /tmp/my movie.dv
As a URI: file:/tmp/my%20movie.dv
As a URL parameter for import: http://localhost:8080/API/import?URL=file%3A%2Ftmp%2Fmy%2520movie.dv (see below)
Note that the space has to be quoted twice. First to %20 in the URI, than the percent sign in %20 have to be quoted to %2520.
Example 2
Path: /tmp/tête-à-tête.dv
As a URI: file:/t%C3%AAte-%C3%A0-t%C3%AAte.dv (UTF-8 is used for the special characters, then percent encoded) (Optionally: file:/tête-à-tête.dv )
As a URL parameter for import: http://localhost:8080/API/import?URL=t%25C3%25AAte-%25C3%25A0-t%25C3%25AAte.dv
Code example
The following Java code, using Jersey’s UriBuilder, shows how to generate valid API calls:
String path = "/tmp/tête-à-tête.dv";
URI uri = new File(path).toURI();
URI callUri = UriBuilder.fromUri("http://localhost:8080/API/import").queryParam("uri", "{uri}").build(uri);
In previous versions of Vidispine, the following call was accepted: http://localhost:8080/API/import?URL=file:/tmp/my+movie.dv. However, this is not valid, as the actual value of the parameter is then file:/tmp/my movie.dv , which is not a valid URI. (However, http://localhost:8080/API/import?URL=file:/tmp/my%2520movie.dv is valid.)
See also