Basic Principles

Params

Path parameters

Path parameters are used to identify entities, represent hierarchies or to provide data to a resoure. They are not intended to filter or restrict information like query parameters (see below). Please do not confuse path parameters with sub resources. A resource can have more than one path parameter, e. g. to represent hierarchical data. Sometimes it is required to supply more than one parameter to a resource for an unique identification of an entity.

Examples:

A resource:

/resource

An entity of a resource (the {id} is a path parameter of the resource):

/resource/{id}

A resource that represents a geo hierarchy (with two path parameters:/key/{value}):

/resource/continent/{Europe}/country/{Germany}

Note: The curly braces are only used to identify parameter values.

Encoding of path parameters

Many values (like usernames) in the path of the URL must be encoded. We use the so called percent encoding

  • encode space as %20, not as "+"
  • don't encode "@" (it is allowed in the path)
  • semicolon ";" must be encoded to %3B (this may change in the future)

See also:

You may use gdata java client's CharEscapers:

/**

* The regular Spring UriComponentsBuilder encoding ignores semicolons.

*@param pathSegment

*@return

*/

public static String encodePathsegment(String pathSegment) {

return CharEscapers

.uriEscaper(false) // false means "no plusForSpace", so %20 .escape(pathSegment);

}

 

Example

A resource that represents a geo hierarchy (with one path parameter representing continents). A GET requests retrieves a list (of xlink references) to all continents:

/resource/continent

A resource that represents a geo hierarchy (with two path parameters representing a continent). A GET requests retrieves the information for the given continent in a specified reprensentation:

/resource/continent/Europe

A resource that represents a geo hierarchy (with three path parameters representing countries of a given continent). A GET requests retrieves a list (of xlink references) to all countries of this continent:

/resource/continent/Europe/country

A resource that represents a geo hierarchy (with four path parameters representing a country). A GET requests retrieves the information for the given country in a specified reprensentation (Note: the country is only unique if you provide the whole hierarchy represented by the path parameters!):

/resource/continent/Europe/country/Germany

A resource that represents a geo hierarchy (with fife path parameters representing states of a given country). A GET requests retrieves a list (of xlink references) to all states of this country:

/resource/continent/Europe/country/Germany/region

To filter the returned states you can use query parameters. E. g. return all states starting with B:

/resource/continent/Europe/country/Germany/region?q=B

This should return the following German federal states: Baden-Würtemberg, Bayern, Berlin, Brandenburg, Bremen. Note: continent, country, and region are path parameters (consisting of a key and a value) in this example and not sub resources.

Query parameters

Query parameters are used to filter or to restrict information of a resource. They are not intended to identify entities of a resource or to select the representation. Do not use query parameters to identify resource entities!

For example, in a search request each query parameter represents a search criterion and restricts the result list - like a filter. Unknown search criteria are ignored (see Query string extensibility) or results in an empty result list.

There are four types of query parameters:

ranges

key=minimalValue-maximalValue (use the - sign between the minimum and maximum value of your range. If one side is empty -## or ##-, then is this meaning from the lowest value or to the highest value of the parameter.)

single parameters

key=value

ordered lists (e. g. ranges)

key=value1;value2;value3;...

unordered lists (e. g. enumerations)

key=value3,value1,value2,...

Note about separators: Members of ordered enumeration types are separated with a semicolon (";"), unordered enumeration types are separated with a comma (","). Query parameters (key-value-pairs) are separated with ampersand ("&").

Note about number values: floating point number values (like longitude/latitude) use the dot (".") as decimal separator (example: geocoordinates=52.512303;13.431191;1). No separator between thousands (example: 12000.123).

Query string extensibility

Query string extensibility means, that a service should ignore any query parameters it does not understand.

An use case is to pass query paramters to subsequent API calls, if the service consumes other services. This allows to add new functionality without breaking existing services.

URI-Specified representation

A client can specify the representation using a query string or as an suffix of the URI:

http://domain:port/path?parameters.xml

The suggested way is to use the specific HTTP Accept or HTTP Content-Type header. For consistency and interoperability concerns, it is important not to mix this TUK-based approach with our standard approach that uses conformant HTTP headers.