Skip to main content

Get Metadata Subtree

GET 
/qlibs/:qlibid/q/:qhit/meta/:path

Retrieve the user-defined metadata at the given path.

If the requested path contains relative or absolute meta links, they are automatically followed. Absolute links require additional auth tokens in order to read the target content object.

The form of the returned metadata depends on the following factors:

  • the optional resolve query parameter
  • the optional resolve_include_source query parameter
  • the optional resolve_ignore_errors query parameter
  • the optional link_depth query parameter
  • the target element at the requested path
  • the requested media types specified in Accept headers (or equivalent header-accept query parameters)
  • the state of the content object (draft vs. finalized)
  • optional query query parameters
  • optional select query parameters
  • optional remove query parameters

If resolve is set to false, the resulting metadata subtree will always be returned in its JSON form, and all links within the subtree are returned as links in their JSON representation.

If resolve is set to true, then the result depends on the target metadata at the requested path:

  • if the target is a rep link, the returned data is the result of a call to the corresponding rep endoint. Any query parameters specified in addition to the accepted parameters of the /meta endpoint are forwarded to the rep endpoint.
  • if the target is a files link, the file's mime type is matched against the requested media types. If there is a match, the file data is returned, otherwise an error.
  • if the target is neither of the above, the metadata is returned in its JSON form as follows:
    • All relative meta links are resolved and their target data is inlined.
    • All absolute meta links up to a link depth specified with the link_depth query parameter are also resolved and their target data inlined. Any absolute link beyond link_depth is added "as a link". The default link depth is 1.
    • If resolve_include_source is present or true, and the inlined metadata is a JSON object, it is annotated with the following json property: ".":{"source":"HASH_OR_TOKEN"}. The annotation is added for both relative and absolute links. The annotation is omitted if the inlined metadata is a simple type (e.g. string, int, etc.) or an array.
    • If resolve_ignore_errors is present or true, and resolving a link fails for whatever reason, the link is included in the result and annotated with the resolution error: "invalid-link": {"/": "...", ".":{"resolution_error":{...}}} Without the resolve_ignore_errors option, link resolution errors fail the entire request and trigger an error response.

If resolve is not specified, then the result depends on the state of the content object

  • if the object is a draft, no link resolution will be performed and the metadata is returned in its JSON form (same result as if ?resolve=false was specified)
  • if the object is finalized, link resolution will be performed as if ?resolve=true was specified, with one small difference: if the highest priority media type is application/json, then file links are always returned in their JSON form instead of the corresponding file data.

See the metadata section for more information on links.

Accepted media types may be specified in a query parameter header-accept as an alternative to Accept request headers. This is useful in situations where request headers cannot be specified, for example in HTML links: <img href="...?header-accept=image/*"/>

See RFC 2616 for details on the Accept request header format.

Retrieve Subtree of JSON File Content Through files Links​

The requested metadata path may extend beyond a files link if the taget file has JSON content (i.e. the file's mime-type is application/json). For example, imagine a file link at path /public/tags that points to the JSON file tags.json. A request to /meta/public/tags/objects/cars will result in reading and parsing the tags.json file, and returning the subtree /objects/cars of the file's JSON data.

The maximum file size is limited to 5 MB per default. Larger files will be served like non-JSON files and don't offer subtree retrieval.

Query & Filter Metadata​

This endpoint also supports the query parameter for filtering the data at the requested path using JSONPath-like expressions. The syntax differs from official JSONPath in the following way:

  • / may be used instead of . to have a more natural path-like structure (like XPath)
  • / may be used instead of $. for the root object
  • array indexes may be specified without brackets: /books/3/price instead of $.books[3].price
  • bracket notation (e.g. $['store']['books'][0]['title']) is not supported. Use regular path expressions instead: /store/books/0/title

Example JSON


\{
    "store": \{
        "books": [
            \{
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95
            \},
            \{
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99
            \},
            \{
                "category": "fiction",
                "author": "Herman Melville",
                "title": "Moby Dick",
                "isbn": "0-553-21311-3",
                "price": 8.99
            \},
            \{
                "category": "fiction",
                "author": "J. R. R. Tolkien",
                "title": "The Lord of the Rings",
                "isbn": "0-395-19395-8",
                "price": 22.99
            \}
        ]
    \}
\}

Example queries

Retrieve the first book.


query: /store/books[0]
\{
  "author": "Nigel Rees",
  "category": "reference",
  "price": 8.95,
  "title": "Sayings of the Century"
\}

Retrieve the price of the 4th book.


query: /store/books/3/price
22.99

Retrieve the price of the 4th book, array index in brackets.


query: /store/books[3]/price
22.99

Retrieve the price for books with start and end index.


query: /store/books[0:2]/price
[
  8.95,
  12.99
]

Retrieve the titles of all books in the "reference" category.


query: /store/books[?(@.category=="reference")]/title
[
  "Sayings of the Century"
]

Retrieve the titles of all books that cose more than 10.


query: /store/books[?(@.price > 10)]/title
[
  "Sword of Honour",
  "The Lord of the Rings"
]

Retrieve the titles of all books.


query: /store/books/*/title
[
  "Sayings of the Century",
  "Sword of Honour",
  "Moby Dick",
  "The Lord of the Rings"
]

Retrieve all title properties in any child element (recursive descent).


query: /store//title
[
  "Sayings of the Century",
  "Sword of Honour",
  "Moby Dick",
  "The Lord of the Rings"
]

Selecting disjoint Metadata Subsets​

The select query parameter may be used in order to retrieve disjoint subsets of the metadata in a single API call. Simply specify the metadata paths of the desired subtrees with multiple select parameters:


/meta?select=/public/defaults/clip&select=/public/clips/fr`

retrieves the default and the french versions of the clip. select queries can be combined with a metadata base path:


/meta/public?select=/defaults/clip&select=/clips/fr

returns the same clips as above, but relative to the public base path. See examples below.

Example JSON


\{
  "public": \{
    "defaults": \{
      "clip": \{
        "/": "/clips/en"
      \}
    \},
    "clips": \{
      "en": \{
        "name": "A walk in the park"
      \},
      "fr": \{
        "name": "Une promenade dans le parc"
      \},
      "de": \{
        "name": "Ein Spaziergang im Park"
      \}
    \}
  \}
\}

Select default and french clips:


request: /meta?select=/public/defaults/clip&select=/public/clips/fr
\{
  "public": \{
    "defaults": \{
      "clip": \{
        "name": "A walk in the park"
      \}
    \},
    "clips": \{
      "fr": \{
        "name": "Une promenade dans le parc"
      \}
    \}
  \}
\}

Same request with base path:


request: /meta?select=/defaults/clip&select=/clips/fr
\{
  "defaults": \{
    "clip": \{
      "name": "A walk in the park"
    \}
  \},
  "clips": \{
    "fr": \{
      "name": "Une promenade dans le parc"
    \}
  \}
\}

Removing Metadata Subsets​

The remove query parameter may be used to remove subsets of the metadata in order to make the API response more compact. Specify one or multiple remove parameters as follows:


/meta?remove=/public/defaults/clips&remove=/public/titles`

Request​

Responses​

The subtree of the metadata at the given path or the binary file data.