URIs

Resources are identified by URIs. This topic explains how to use URIs when working with the REST API.

URI syntax

Resources are identified by URIs:

  • URIs are used to uniquely identify resources.

  • URIs follow STD66 and RFC 3986.

  • URIs are case sensitive, including entity and field names. For example, the field id is correct, but ID is incorrect.

  • URIs have the following generic syntax: 

    <scheme name>:<hierarchical identifier>[?<query>]

Note: For the syntax for specifying parameters in URIs, see Variables and values.

Back to top

Scheme name

Scheme is mandatory.

The http/https schemes are the only ones supported.

Back to top

Hierarchical identifiers

The hierarchical identifier is mandatory.

The hierarchical identifier has the following generic syntax: 

//<authority><path>

Begins with two slashes ("//").

Hierarchical identifier Description
Authority

  • Authority is mandatory.

  • Authority has the following generic syntax: 

    <host name>[:<port number>]

  • Host name is separated from the port number with a colon ( : ).
Host name

  • Host name is mandatory.

  • Host name can be defined by the domain name (DNS domain).

  • Host name can be defined by an IP.
Port number

  • Port number is optional.

  • Port number is a 16-bit integer.

  • Port number is separated from host name by a colon (:).

Path

  • Path is mandatory.

  • Path has the following generic syntax: 

    [[/<Segment Name>]]

  • Path represents a sequence of segments.

  • Segments are separated by a slash (/).

Back to top

Queries and other URI clauses

Here are guidelines for using queries and other clauses in the URI.

URI component Guidelines
Queries

  • Queries and other clauses are optional.

  • Queries have the following generic syntax: 

    ?<parameter name>=<parameter value>[[&<parameter name>=<parameter value>]]

  • Queries are separated from the hierarchical part by a question mark (?).

  • Queries are organized in parameter name/value pairs.

  • Pairs are separated by ampersands (&).
Parameters

  • Parameters contain a name and a value.

  • Parameter names and parameter values are separated by an equals sign (=)

  • Parameter names are case sensitive.

  • Parameter values are generally not case sensitive.

The following clauses can also be appended to a URI:

Back to top

See also: