Link relation taxonomies:search

Overview

Find taxonomy entries that match a given search condition.

HTTP method

POST

URL template parameters

-

Query parameters

sort

(Optional) The sort order for the returned entries. The value is a comma-separated list of sort specs, each consisting of:

  • An optional prefix "+" for ascending order or "-" for descending order). If not given, ascending order is used.

  • A property of the entry. One of:

    • id: The entry ID.

    • label: The localized label of the entry.

    • The name of an attribute.

Example for an MC|AM legal list taxonomy: sort=label,index,-id to return entries sorted primarily by localized label in ascending order, then by the entry attribute index in ascending order, then by entry ID in descending order.

The query parameter may be ignored by the service. Currently, sorting is only supported for MC|AM legal lists.

limit

The maximum number of matches to return. This parameter is used for paging. If missing or invalid (less or equal than 0, or higher than the maximum value of 1000), the default is 25.

offset

The offset within the search results. This parameter is used for paging. If missing or invalid (less than 0), the default is 0, meaning that the results are returned beginning with the first element.

embed

A comma-separated list of sub resources to embed. Possible values:

  • path-to-root: embeds the taxonomies:path-to-root resource for the entry in the result set.

  • path: (only if path-to-root is also embedded) embeds the path entries that are referenced in the taxonomies:path-to-root resources of the result set.

Request body

The search specification in JSON format. See taxonomy search specification for details.

HTTP response

200 OK

Response body

The matching entries

Available in

Taxonomy search specification

Properties of a search specification:

  • quick: defines a quick search or full text condition. Sub properties:

    • query (string) The search term.

    • scope (optional, string) Defines the scope of the search. If not given, the service uses a built-in scope. The scope is defined with the sub properties:

      • label (boolean): If true, an entry matches if the display label contains the query

      • attributes (string array): An array with the names of the attributes that are searched. Depending on the capabilities of the service, some attributes are probably not searchable and will be ignored.

An entry is usually a match if a searched attribute contains the given query string as a sub string. However, for some taxonomies of some systems, the behavior may be different.

The search specification format may be extended in future releases.

Examples

Example for minimal search specifications for quick search:

{
  "quick": {
    "query": "violin"
  }
}

Example with a scope, searching for "violin" in the display name and the attribute "synonyms":

{
  "quick": {
    "query": "violin",
    "scope": {
      "label": true,
      "attributes": [ "synonyms" ]
    }
  }
}

MC|AM

In MediaCentral | Asset Management, the search behavior for taxonomies of type master data is configurable, depending on the customer’s needs. The default configuration searches for entries that have the given text as sub string, but there are also options to search for entries that have exactly the given text and nothing before or after it as value of an attribute, or have the given text as a word, or contain a word that starts the given text.