Query Link Relation

Irakli Nadareishvili edited this page Oct 17, 2013 · 4 revisions

Query Link Relation

Query link relation is one of the most important, core link relations for the Collection.doc+json media type. It is inspired by the Queries Link Relation from the Collection+JSON media type and the Home Document for HTTP APIs spec. Query link allows an API to communicate to the API clients what kind of contextual queries they can run against the content in the API.


The syntax of the link used in the Collection.doc+json media type is based on the syntax of the Resource Objects in the Home Document for HTTP APIs v3 specification by Mark Nottingham and can look something like the following:

links {
  "search"    :  [ { "href" : "A direct URI",   "title": "Description of the query"}
                 , { "href-template" : "URI Template",   "title": "Description of the query"}
                 , { "href-template" : "http://pmp.io/docs/{?color,tag}"
                   , "title": "Search by a color and a tag"
                   , "rels" : ["urn:pmp:query:docs]"]
                   , "href-vars": {
                       "color" : "http://example.org/param/color"
                     , "tag"   : "http://example.org/param/tag"
                   , "hints": {
                       "allow": ["GET"],

Following is the relevant excerpt from the Home Document spec adapted for the JSON syntax of the search link relation of Collection.doc+json media type:

The JSON object of a search link relation links to resources of the defined type using one of two mechanisms; either a direct link (in which case there is exactly one resource of that relation type associated with the API), or a templated link, in which case there are zero to many such resources.

Direct links are indicated with an "href" property, whose value is a URI [RFC3986].

Templated links are indicated with an "href-template" property, whose value is a URI Template [RFC6570].

When "href-template" is present, the search link MUST have a "href-vars" property to facilitate successful resolution approach.


Optional. Human-readable title of the search link explaining the purpose of the link.


href-template is a templated link pointing to a search endpoint. A URI can be derived from a Templated Link by treating the "href- template" value as a URI Template [RFC6570], using the "href-vars" property to fill the template.


The "href-vars" property, is an object that acts as a mapping between variable names available to the template and absolute URIs that are used as global identifiers for the semantics and syntax of those variables.


Optional. This property can provide several hints about interacting with the search resources, for instance: the HTTP methods usable with them

If a hint is missing that does not mean that certain funcionality (e.g. an HTTP method) is not supported. It means that the client will need to discover this by interacting with the URI resource, and/or examining the documentation for its link relation type.

For more details regarding various supported hint types, please see: the Home Documents for HTTP APIs spec.

Problem space: AND and OR list values for search filtering

Very commonly, in a search query, we want to be able to say things like:

  1. "find me all resources where color= red OR green OR blue".
  2. "find me all documents that are tagged by "elections" and "senate"

In effect we must be able to construct queries where a parameter has multiple values and these values are joined either by an "OR" relationship, or an "AND" relationship.

For the sake of simplicity we will assume that all values are either joined by an "OR", or by an "AND", but we do not have to currently suppor an expression which mixes "OR"s and "AND"s. Expressions for the queries described above, then would be:

  1. color = "red" OR "green" OR "blue"
  2. tag = "senate" AND "elections"

Expression Serialization Rule

For serialization/deserialization we use URI Templates (RFC6570) with Form-Style Query Expansion syntax and some additional semantics.

For instance, the query described above could be represented by a URI Template that looks like the following:


Additional semantical rule that Collection.doc+json employes states:

variables in the search URI templates can be literal values or can be a list of values delimited by a separator. Furthermore, using comma (",") as a delimiter is interpreted as an "AND" relationship, while using semicolon (";") is interpreted as an "OR" relationship between the list elements.

In such approach, a query like: "find me resources that have color "red", "blue" or "green" and are tagged with "elections" and "senate" would look like:


Pros of Such Serialization:

We could have chosen other serialization approaches. Some of the reasons why the described method was chosen:

  1. Resulting URI looks quite intuitive for a human eye, which makes things easier to debug and less error-prone

  2. Serialization approach is compatible with the URI Template spec.

  3. If needed in the future, the suggested serialization approach can scale to more complex custom expressions. For instance, we could easily introduce a "range" delimiter to be colon (":") and use expressions like: 2000:2015 meaning: some value between number 2000 and 2015. Furthermore, in some future version, our media type could even support a complex expression that looks like:


which would stand for: give us all resources that are tagged: "obama" OR "biden" AND "elections".