Overview

There are several service lines that operate on the same principle. The end points are slightly different but the parameters are the same and depending on the configuration the possibilities are identical. All the details are available in the https://crossmedia.atlassian.net/wiki/spaces/WD/pages/732364803 section. This page describes the general principle of accessing resources, individually, in lists, in trees, etc.

All parameters and resources are not described in this page. For an exhaustive list of parameters and resources, consult the API documentation (ReDoc or Swagger) of the server on which you want to invoke an end point.

Types of services

The API is divided into service types:

• The DAM services concern general access to DAM resources. The identifier for this type is dam. The URI of all end points for this type starts with /api/rest/dam.

• The DATA services are additional services specifically configured according to the needs for a given environment. The identifier for this type is data. The URI of all end points for this type starts with /api/rest/data.

• The PROFILE services are dedicated to the manipulation of the data of a user by himself. The identifier for this type is profil. The URI of all end points for this type starts with /api/rest/profil.

• The MASSIMPORT services are dedicated to mass data upload. The identifier for this type is massimport. The URI of all end points for this type starts with /api/rest/massimport.

• The APPSETTINGS services are dedicated to the configuration. The identifier for this type is appsettings. The URI of all end points for this type starts with /api/rest/appsettings.

Table of contents

Get a resource

The access to a resource can be done by its identifier.

• verb: GET

• general form of the URI: /api/rest/{type of service}{/name of the resource type}/{id}

Get a resource by its unique identifier

GET /api/rest/{type of service}/{uniq identifier}

For example, to get an asset with uniq identifer xypoj1eouw7fj5n8mwdaxwjeyc from DAM : GET /api/rest/dam/xypoj1eouw7fj5n8mwdaxwjeyc.

The result is a JSON object composed of several sections:

• the data of the requested resource, located at the path $.response.data

• data on the type of resource (its identifier, its name (localized), its description...)

• possibly the description of the properties of the resource, the headers

• a section of HATEOAS links

• possibly debugging information

The general form of the resource at the $.resource.data path is an object whose properties are the properties of the resource. There are several categories of properties:

• Simple properties, such as the name of the resource, or its identifier.

• Properties designating another linked resource.

  • When the link is unique, the value of the property is an object (or null if the property is empty). This object has the same shape as the main resource, recursively.

  • When the link is multiple, the value of the property is an array of objects. These objects has the same shape as the main resource, recursively. There may be additional technical information to be able to retrieve all the values from the list of linked elements (see Accessing children )

• Possibly technical data (whose name begins with the dollar sign)

  • type of resource

  • preview urls

  • rights and facets / faces

  • possible workflow actions

  • related information

  • etc.

See examples and a sample resource here.

Get a resource by identifier

GET /api/rest/{type of service}/{name of the resource type}/{identifier}

The identifier of a resource is unique for the type of resource it is part of. This is why it is necessary to specify in the URI the name of the resource type in addition to the access URI by a unique identifier.

For example, to get a resource with id 42 from the ressource productcode within the type of service DATA: /api/rest/data/productcode/1.

For the DAM service type, it is necessary to indicate that you want to access a resource directly via the additional data path (following the type of service dam, and preceding the name of the resource type).

For example, to get an asset with id 1 from DAM : GET /api/rest/dam/data/asset/1.

The resource obtained will be exactly the same as with access by unique identifier.

The unique identifier can also be used instead of the identifier in the resource type. For example, /api/rest/dam/data/asset/78j1ko1ds3my1. You can omit the resource type, especially if you don't know it.. The /api/rest/dam/data/78j1ko1ds3my1 URI will give exactly the same result as the previous URI (because this unique identifier is that of an asset).

See examples and a sample resource here.

Get a resource list

Get list

This service allows you to obtain a list of resources, or to search for resources matching a query by criteria, or full text expression.

• verb: GET

• general form of the URI: /api/rest/{type of service}{/name of the resource type}{/list}

Infinite list

GET /api/rest/{type of service}/{name of the resource type}

This end point retrieves the list of resources of the specified type. For example, to get the list of assets : /api/rest/dam/data/asset. To get the list of resources from type productcode within the type of service DATA: /api/rest/data/productcode.

The result is a JSON object very similar to the one obtained when requesting a resource by its identifier. The sections are:

• the list of requested resources, located at the path $.response.data, as an array of objects of the same format as you would get for a resource obtained by its identifier.

• counters

  • total
    This is an estimate of the total number of resources requested. The value may not be completely accurate due to systems that may filter resources based on caller rights. In the best case, it is equal to the maximum number of resources, but it can be more often than not greater than the number of resources that will actually be obtained if all of them are requested, notwithstanding the fact that this number can vary if resources are created, deleted or even modified (because of sorting).

  • trueTotal
    This is the exact total number of resources requested, if determinable (otherwise, the value is null)

  • count
    This is the number of resources actually contained in the section corresponding to the $.response.data path. It is necessarily less than or equal to the maximum requested.

• data on the type of resource (its identifier, its name (localized), its description...)

• possibly aggregates (see Aggregates)

• possibly the description of the properties of the resource, the headers

• a section of HATEOAS links

• possibly debugging information

See a sample resource here.

Get all the resource of a type

It is not possible to retrieve all resources of the specified type. You can retrieve a fixed maximum (see Limitation in the number of elements in a list). To be able to retrieve the following ones, we use the same end point specifying that we want those after the last resource obtained, using a token. To find out if you did not get all the resources matching the query, just look at the HATEOAS links section.

Here is an example (here, it is the response obtained for a call to /api/rest/dam/data/asset, without any particular parameter):

• moreResultsToken: this property designates the token that should be used to obtain additional results

• nextResultsToken: this property designates the token that should be used to obtain the results following the last resource in the result list of the request. It is the same token as moreResultsToken when doing a list query in the normal way, from the beginning, where you get the first ones, then the next ones, then the last ones.

• previousResultsToken: this property designates the token that should be used to obtain the results preceding the first resource of the result list of the request. It is the same token as moreResultsToken when requesting a list in the opposite direction, from the end, where we get the last, then the previous, then the first ones. In this example, it is null, because we are at the beginning of the list, and, therefore, there are no elements preceding the first obtained in the result of the request.

• the other properties are the URLs autogenerated from the parameters and tokens, to get the same results, the next results in the list, or the previous results, if any.

Paginated list

GET /api/rest/{type of service}/{name of the resource type}/list

The results for a paginated list are the same as for an infinite list, except that instead of tokens and URIs allowing you to get next or previous, you will get the page positions in the existing set of resources, and URIs allowing you to get the next or previous page.

The counters are also slightly different:

• total
  This is an estimate of the total number of resources requested. The value may not be completely accurate due to systems that may filter resources based on caller rights. In the best case, it is equal to the maximum number of resources, but it can be more often than not greater than the number of resources that will actually be obtained if all of them are requested, notwithstanding the fact that this number can vary if resources are created, deleted or even modified (because of sorting).

• trueTotal
  This is the exact total number of resources requested, if determinable (otherwise, the value is null)

• count
  This is the number of resources actually contained in the section corresponding to the $.response.data path. It is necessarily less than or equal to the maximum requested.

• first
  the position (from 1 to n) of the first resource obtained in the complete list of resources that can be obtained

• last
  the position of the last resource obtained in the complete list of resources that can be obtained

See a sample resource here.

For the same reasons as for an infinite list, it is not always possible to determine the total number of resources, but if it is, you can also get a link to the last page.

Here is an example (here, it is the response obtained for a call to /api/rest/dam/data/asset/list, without any particular parameter):

Get a list of resources in tree form

Get a tree

Some types of resources are configured to be presentable in a hierarchical, tree-like form. This is the case for example with thesauri.

• verb: GET

• general form of the URI: /api/rest/{type of service}{/name of the resource type}{/list}

Get the resources in tree form

The request is the same as for obtaining a list (so we can obtain a tree in infinite or paginated mode). It is enough to indicate in addition some parameters:

• depth: the depth we want to obtain.

  • If the depth is 0, we get the nodes of the tree on a single level, as if we were asking for a list (but we only get those on the corresponding level)

  • If the depth is positive, we get as many levels of depth.

  • If the depth is -1 or less, we get all the levels that exist

  • If the depth is null, or any other value, or is not present, we get a list.

• treeprop: the name of the pivot property. In general, a tree resource type has only one pivot property and it is therefore not necessary to specify (and therefore know) this parameter. But if there are several properties in a resource that is a link to the same type of resource, it is possible by this property to follow the tree structure by specifying its name via this parameter

• treetop: combined with the treepath parameter (it is enough that there is one of them), allows to obtain a breadcrump, that is to say a branch of tree resources from one level to another. In this case, treetop is the number of levels we want to obtain

• treepath: combined with treetop (you only need one of the two parameters) allows to define the direction of the breadcrump

  • ascendant, a, asc… to go up to the top

  • descendant, d, desc… to go down to the bottom

• treepathprops: in the case of a breadcrump, allows you to list the properties you want for the parent or child resources in the breadcrump. By default, without indicating this parameter, we will only obtain the names of the resources.

• withSynonyms: a boolean that allows you to specify that you also want the synonyms (if the resource is a thesaurus)

• withRelated: a boolean that allows you to specify that you also want the related terms (if the resource is a thesaurus)

Get a tree from a specific resource

To get the subtree from a particular resource, you just have to specify in the uri the identifier, or the unique identifier of the resource. For example, to get the tree of geographic location ressources from the location "Africa": /api/rest/dam/data/assetgeography/2?depth=-1 or /api/rest/dam/data/783if7sieq1dudd8znndsc8catn37xj1hfd5p5a?depth=-1.

See a sample resource here.

Presentation of the results

The information in the pivot property is slightly different in the case of a tree. In addition to its identifier and name, you will get a technical property $children which presents in array form the children of the resource.

The $treepath property contains the breadcrump, either as a name array or as a resource array if treepathprops was used to get specific properties

Optimized tree service

• verb: GET

• general form of the URI: /api/rest/{type of service}/{name of the resource type}/tree

This end point allows you to obtain a tree more quickly than with the list service.

The keyword mode

The keyword mode provides the best performance for tree retrieval. However, it has limited possibilities compared to other ways of obtaining a tree:

• fulltext search is not supported. Instead, we have a search mode limited to string operators:

• the sorting is limited to one field, by default the name. It is possible to impose sorting by configuration or by request parameter

To activate the keyword mode, specify the keywords=true parameter. For example, /api/rest/dam/data/assetgeography/tree?keywords=true.

See a sample resource here.

The hybrid mode

This mode uses the same system to obtain the tree, but allows to obtain the same information that we would obtain in list. It has an intermediate performance. It is not recommended to use this mode for large volume trees, especially if there are many properties exposed for each resource. As an indication, the average ratios are 100 for the list mode, 1 for the keywords mode, and 15 to 30 for the hybrid mode.

It is still preferable to the list mode if you don't need full text search or sorting on several properties, but you need to get all properties of each resource.

Full text search

Full text search is not supported by this service. Instead, a string search is available, in keyword mode only.

Use the find parameter in this way:

• If it starts with equals:, we look for terms that are equal to what follows. For example equals:martinique searches for resources whose name is « martinique ».

• If it starts with startsWith:, we look for terms that start with the following. For example startsWith:landscape searches for resources whose name starts with « landscape ».

• If it starts with contains:, we look for terms that start with the following. For example contains:mountain searches for resources whose name contains « mountain ».

• If it starts with in:, what follows is considered a comma-separated list of words, and we look for terms that are equal to at least one of the words. For example in:mountain,beach searches for resources whose name contains mountain or beach. if one of the searched words contains a comma, escape it with a backslash. For example in:New York,Washington\, D.C. searches for resources whose name is « New York » or « Washington, D.C. ».

See a sample resource here.

Get suggestions

The search can be used to get suggestions. Typically, we pass in the find parameter the beginning of a word and we get the corresponding search suggestions. For example, pass "cub" and you get "cub", "cuba", "cube", "cubaa", "cuban", "cubana".

Standard suggestions

To obtain the suggestions, we use the infinite list end point, specifying the suggest (or suggestions) parameter:

• suggest=true, to get the suggestions in the same form as for an infinite list

• suggest=words, to get only the names of the resources, in a compact form. In this case, the property corresponding to the $.response.data path is an array of the resource names (strings).

• suggest=false, or no value, or no parameter, to get an infinite list (by default)

The general form of the answer is therefore very similar to that of an infinite list but there is additional technical information qualifying the suggestions. See description for more details.

Search: full text and query

The full text search

Specify the phrase you are looking for in the find parameter.

The fulltextInFile parameter enables full text search inside files. For example, /api/dam/asset?find=landscape&fulltextInFile=true.

The fulltextMode parameter allows you to change the search mode:

• should: We find the resources that match one of the words

• must: Find resources that match all word

• any other value or no value or no parameter: default mode is used

The query search

It is possible to search by criteria, using the query parameter. The syntax of this parameter is described in the https://crossmedia.atlassian.net/wiki/spaces/WD/pages/16679121 chapter. The query applies to all resources. Also in the case of a tree: to apply the query only to the highest level resources, use the rootquery parameter. In the case of multi resource type queries, the query is applied to all resource types. To apply a specific query to a type, suffix the parameter name with the name of the resource. For example, to make a search on asset libraries with specific query on legacy library : /api/dam/asset?query={"status":"published"}&query_legacy={"status":"archived"}.

Sorting resources

To sort the results, use the orderby parameter. This is a list of sorting criteria separated by commas and whose importance goes from left to right: first we sort on the leftmost, then on the second leftmost, then the third and so on. A criterion can take the form of:

• a property name, for an ascending sort

• a property name followed by a sort order (separated by at least one space from the property name)

  • a or asc for an ascending sort (from smallest to largest for example)

  • d or desc for a descending sort (from the biggest to the smallest for example)

Sort by relevance

The sortByRelevance parameter allows you to choose if you want a sort by relevance or not. If relevance sorting is activated, the most relevant results are presented first.

• sortByRelevance=true activates sorting by relevance

• sortByRelevance=false deactivates sorting by relevance

• if the parameter is not specified, or the value does not correspond to a boolean, we apply a default behavior:

  • if no fulltext parameter or if there is a query, then we deactivate the sort by relevance

  • otherwise we activate the sorting by relevance

• sorting by relevance has no effect if there is no fulltext parameter

Combine full text and query

It is of course possible to combine the two types of search in the same query.

Filter resource properties

Resources are configured so that certain properties are exposed or exposable via the API:

• properties or metadata specific to the resource, or properties or metadata of resources linked to the resource

• technical properties

  • automatically exposed by default

  • exposed on demand (in response to the use of certain request or configuration parameters)

You can restrict the number of properties exposed for a resource by using:

• The props parameter to restrict the properties or metadata specific to the resource. See the documentation of this parameter for more details (https://crossmedia.atlassian.net/wiki/spaces/WD/pages/2209742855) or Swagger API documentation.

• The techprops parameter to restrict automatically exposed technical properties. Technical properties are those whose name begins with the $ character. See the documentation of this parameter for more details () or Swagger API documentation.

Multi-resource access

It is possible to get an infinite list (so to search) on several types of resources at once. It is necessary that if a query is used (query parameter), it is valid for all the resources. It is possible to specify a different query for each type of resource (See The query search).

Search in any resources

To search in any resources (of the same service type only), it is enough to indicate the comma-separated list of names in the URI of the infinite list endpoint, where the name of the single resource is usually indicated.

For example, /api/rest/dam/data/asset,legacy to process asset and legacy libraries.

Search in any libraries

All libraries can be specifically searched in a single query, in the DAM service type only, using the URI / /api/rest/dam/asset. Typically, environments have three basic libraries: asset, brand and legacy. The URI /api/rest/dam/asset therefore corresponds to /api/rest/dam/data/asset,brand,legacy.

Search for assets of a specific nature

Instead of asset, you can indicate the specific nature you are looking for. For example, /api/rest/dam/image searches for images among all the libraries. Use the name of the nature (only root), which you can get by api/rest/dam/data/assetnature?props=name&lang=en&query={primarytype: {e:null}}. Other examples:

• /api/rest/dam/video

• /api/rest/dam/document

• /api/rest/dam/3d%20models

• /api/rest/dam/print

• /api/rest/dam/archive

• …

Accessing children

If a resource type has a multiple link property, we can get the resources linked to a resource directly without asking the main resource.

Its URI is of the form /api/rest/{type of service}{/resource name}/{id of resource}/{property name}. We can repeat the end, for each child of the resource, to obtain its children.

For example, if we want to get the children for the field books of the resource of type bookcase and id 2417, we’ll use the URI /api/rest/data/bookcase/2417/books. If resource of type book has a multiple child to a resource of type page, by the field pages, we’ll use the URI /api/rest/data/bookcase/2417/books/127/pages to get the pages of the book with id 127. And so on.

To get the children in an infinite list, use the nextToken parameter, and from for a paginated list.

Querying children of topmost property

It is possible to filter the lists of resources linked to the topmost property by passing a query in the parameter childQuery, suffixed with the name of the property. For example, for the property location, user childQuery_location.

Counting

With the list services (infinite or paginated) you can get only the counters (number of occurrences) without the data of each resource with the parameter withData set to false. For example /api/rest/dam/data/asset?withData=false.

Aggregates

Aggregates are counters of the same value of a metadata. For example, if a resource has a location property, giving the geographic location, asking for the aggregates on that resource will give you the number of resources with each separate location value, so the number of resources in France, Italy, Thailand, etc.

These counters take into account the search criteria of the query (full text and query).

Aggregates in lists

To get the aggregates, use the parameter withAggregates=true. You can also set withData to false to avoid getting the resources themselves. For example, /api/rest/dam/asset?withAggregates=true&withData=false. Aggregates can be requested for infinite lists, paginated lists and even trees.

You can filter the information of aggregate sections by the parameter aggfields. See details on the use of this parameter in chapter Filter fields and resource properties just below.

See a sample resource here.

Parameters

• aggNotAssigned

• aggTreeCount

• aggMinOccurs

• sortAggsOnName and aggSortFieldnames

  • aggSortFieldnames

  • sortAggsOnName

Limits

Specific aggregate service for filters

This service allows to obtain aggregates for complex queries from combinable filters (and, or...).
To see the details of the use of this service, see the chapter Filter aggregates.

Filter fields and resource properties

The aggfields parameter allows (like the props parameter) to filter the information exposed for each aggregate value, but also the fields for which you want to get aggregates. The syntax is quite similar but nevertheless different.

• It is a list of fields separated by a comma. Aggregates can only be requested for fields that have been selected for. For example, aggfields=coverage,assetnature,keywords.

• It is either simply the name of the field. In this case the properties configured for this field, usually the identifier and the name, are exposed. For example, aggfields=coverage,assetnature,keywords.

• The list of property names separated by commas can be indicated in parentheses after the field name. For example, aggfields=coverage(id,name),assetnature(id),keywords(name).

• If the parentheses are empty, the list of properties of the previous fields is selected. For example, aggfields=coverage(id,name),assetnature(id),keywords() is the same as aggfields=coverage(id,name),assetnature(id),keywords(id)

• The list of properties, without fields, is applied for all fields (fields selected by default). For example, aggfields=(id).

Presentation of the aggregates

Aggregates are found in the section at path $.response.aggregates in the form of a JSON object, each property of which is a field, the value of which is an array of counters.

For each counter, we find:

• a count property, the number of values

• a data property, the properties of the counted value (depending on the configuration and the aggfields parameter)

See more details here.

Get binaries

See the documentation to get binaries

Groups

The infinite list service has a grouping option. It is possible to structure the data in groups determined by one or more properties. A group is therefore made up of a header, the grouping value, and a list of resources, those that have this value for the grouping property or properties. The groups themselves can be grouped. You can't group by any property. See in the headers, or in the configuration of the service, which properties allow grouping. Grouping on a property requires that the sorting be done on that property.

The grouping is done by the parameters group and grouplevel.

Another type of grouping is available from version 2023.4.0 (see extended groupings).

The group parameter

This parameter defines the groups.

• This is a list of grouping definitions, separated by semicolons, called levels.

• A level is defined by a list of selectors separated by commas. This definition is optionally followed by a colon and an integer number that constitutes the maximum number of resources to be obtained for the level.

• The selector is a property name, possibly followed by a sort order after a space, either asc for an ascending sort, or desc for a descending sort)

For example, group=coverage,created asc:10;status desc, which first groups on coverage and creation date, with a maximum of 10 results, then groups according to status, with a descending sort. This defines 2 levels of grouping.

See sample

dof instead of equals

By default, a group level will contain all the resources (up to a specified maximum), which have the same value for the properties of the selectors defining this level. If the name of a property is preceded by the character >, the grouping operator is dof (descendant of) instead of equals. That is, we will get all the resources that have the same parent (this implies that the property in question should be a thesaurus, or a tree).

grouping by date field

It is possible to group according to a date field when the property is of type date, by preceding the name of this property by one of the following field selectors:

• (y) (or (year)) to select the year

• (m) (or (month)) to select the month

• (q) (or (quarter)) to select the quarter

• (h) (or (halfyear) or (half-year)) or (s) (or (semester)) to select semester

• (w) to select week (ISO, so starting on monday)

• (ws) to select week (starting on sunday)

For example, (m)created, will give a group of resources created in January, one of those created in February, one of those created in March, etc.

When we group on a field, we necessarily group on the higher order fields. For example, if we group by month, we will have groups by month of each year, not just 12 groups by month that cover all the years.

grouping by string beginning

It is possible to group according to a part of a character string, by preceding the name of the property with a defined formula as shown below:

• the formula must be between parentheses

• it must start with the @ character

• this @ must be followed by an integer strictly greater than 0, that is the number of characters to compare to group

By example, if the definition is (@1)name, all resources whose name begins with A, all resources whose name begins with B, all resources whose name begins with C, etc

strings starting with numbers

Digits are treated like any other character. You can group all values that start with a digit into a separate group (all assets whose property starts with a digit are part of a single group), by adding a # to the end of the parameter. For example (@1#)name, to get resources whose name begins with a digit, then resources whose name begins with A, then resources whose name begins with B, then resources whose name begins with C, etc.

The grouplevel parameter

This is a number that determines the level of the group you want to obtain (it must be less than the number of levels requested), which allows you to obtain a subgroup directly.

Extended groupings

Since 2023.4.0

The group parameter can be used to define a grouping system based on aggregates. It is no longer necessary to sort the main data. But you are limited to a single grouping level for each property.

Only the group parameter is used, but it is always combined with the other parameters. The query parameter (and derivatives) serves as a data filter, props lists the properties of asset to return, while the max parameter indicates the maximum number of data items (including groups), etc.

The group parameter

This parameter defines the groups. It’s a JSON object, with at least a property groups to define groups. This property can have two forms: array or object.

Array form

In this form, each array element defines a grouping, via a JSON object. A property of this object, groupId, defines a grouping identifier that enables the results of this grouping to be retrieved in the response. The other properties describe how to group, and are detailed in section Grouping properties below. If no identifier is specified with property groupId, an automatic identifier will be assigned.

Object form

In this form, the object properties are the group identifiers and the associated value a JSON object that describes the grouping properties as shown in section Grouping properties below.

Other properties at root

• props: exposed properties for group data.

• max: maximum number of data instances per group

• groupMax: maximum number of groups per result

• aggLimit:

• format: style of response (1, 2 or 0 by default)

• sortedByNames: true (by default) to sort groups by names (ascending), false to not (sort by id)

Grouping properties

There are different ways to describe a grouping.

By property

In this mode, we indicate the asset property by which we want to group, using the prop property.

For example, if you want to group assets by assetnature:

By metadata type

It is possible to specify the type of metadata (i.e. the type of grouping property, or nature), using type property (or nature property).

For example, if you want to group assets by assetkeyword nature:

Please note that if there are several properties of this nature, the service will return an error to indicate that it cannot determine which property should be used. In this case, you'll need to specify the property name. You can specify both, but this will require a type check.

By UUID of metadata instances

The id property, a string or an array of strings, indicates the uuid (or uid) of objects to be selected as grouping values. A simple id can be indicated if a sufficient description of the property and nature (by prop and/or type) has also been specified.

Describing a group with a simple string

This string will be considered as a metadata UUID You can also use an array of strings to indicate several UUIDs.

Common properties

These properties describe the characteristics of the grouping and the data returned, for the group in particular. Some of them can be specified in the global section of the group parameter (see Other properties at root above).

• ope (or operator)
  Depending on the type of grouping property, a default operator is used to select the aggregate (This operator can be derived as "is empty" if the value to be tested is empty or null.). This property allows you to modify this default value.
  Default operators by type

  • for a child(arbo_field or thesaurus) DOF

  • for a child(neither arbo_field nor thesaurus) EQ

  • for a collection IN

  • for a childmulti (arbo_field or thesaurus) DOF

  • for a childmulti (neither arbo_field nor thesaurus) IN

  • else: EQ

• groupQuery (and its suffixed derivatives by type)
  A filter to be applied to the grouping data query. This filter uses JSONQuery syntax.

• dataQuery (and its suffixed derivatives by type)
  A filter to be combined with the main query on group data. This filter uses JSONQuery syntax.

• find
  A fulltext filter to be combined with the main group data query

• groupAfter
  A token allowing you to request the groups following those obtained previously.

• dataAfter
  A token to request the assets following those obtained previously.

• max (or dataMax)
  Maximum number of assets per group (default is 3, max is 20)

• groupMax
  Maximum number of grouping instances per group, i.e. groupId (default is 20, max is 50).

• aggLimit
  Aggregate limit configuration

• props
  Properties of grouping instances to be exposed (default id and name).

• notAssigned
  A Boolean used to indicate that a grouping instance of type metadata has no value (a UUID corresponding to an ID of value 0 can also be indicated, with property id).

Result

To summarize, the response/data section of the main query is an array of sections (JSON Object) made up as follows:

1. in groupData property, an object to describe the group

2. in data property, an array with the asset (or any other data) corresponding to the group (having the corresponding metadata)

3. in nextData, the value of the group parameter that should be specified to obtain the rest of the data for this group, or null, if all the data have already been obtained

4. some additional data

   1. total: the total number of data that can be obtained for this group

   2. count: the number of data obtained in this response

   3. complete: true if all the data in this group have been obtained (specifically, if there are no more data in this group after the last one obtained in this response)

   4. nextToken: if existing, the token to build a nextData section yourself

In response, at the same level as data, a section group (array) with, for each groups, an object containing these properties

1. groupId, the ID of the group

2. nextGroups, the value of the group parameter that should be specified to obtain the rest of the group data, or null, if all the groups have already been obtained

3. total: the total number of group instances (metadata instances) for this group

4. count: the number of group instances for this group in the current response

5. complete: true if all the group instances have been obtained

6. nextToken: if existing, the token to build a nextGroupssection yourself

In addition, the link section contains sections of the nextData or nextGroups type, grouped together to obtain the rest of the data in a single query if required.

Exemple

Let's take the request https://example.wedia-group.com/api/rest/dam/data/asset. It returns 8140 instances, 50 by 50.

We add the following group parameter:

We require two different groupings

• one for identifier location, which groups according to the location property (assetgeography type)

• the other for identifier author, which groups according to the photograph property (assetauthor nature).

With max=4, author groups will have 4 assets max for each photographer, and location groups will have 3 assets max for each location (3 is the default value).

Here is a summary (simplified) of the response:

Let’s have a look to nextData just above:

If you redo the request https://example.wedia-group.com/api/rest/dam/data/asset with this value for group parameter, you will get the following 3 assets, and if you do it again, you will get other 3, and so on, until you’ll get the last of 10, and a null nextData, and a complete equal to true.

With nextGroups just above, you’ll get the missing assetauthor instances, with their assets, and a nextData for each one where it’s necessary.

In the links section, you’ll get also a summary of groups and data:

• groups, an array of each group, to know which are complete

• nextGroups: the parameter to get next groups

• nextData: the parameter to obtain all subsequent data for all groups already obtained (those in this response for which data remains to be obtained).

Clusters

It is possible to export collection properties in clusters, when they are of tree type (i.e. a property of the collection object is of the same type as the collection itself).

To do this use the clusterdepth parameter:

• a strictly positive integer defines the display depth

• a strictly negative integer indicates an infinite depth

• any other value, or no value, or no parameter, disables the cluster mode (by default)

Limitation in the number of elements in a list

For performance reasons, the number of resources that can be obtained in a response is limited. By default, a maximum number of resources is returned, which can be modified, with an unsurpassable maximum.

Maximum in list

The absolute maximum number of resources in a list is 250. The resource configuration may impose a lower maximum. The default maximum number of resources is 50. You can use the max parameter to change the maximum number of resources you want to get, but it will not exceed the configuration maximum, nor the absolute maximum number.

To get the next ones, use the parameter after or before, for an infinite list, or from for a paginated list.

Maximum for aggregates

The absolute number of aggregates (of value for which we have a counter) that we can obtain is 200. By default it is 20. The parameter corresponding to max for the aggregates is limit.

However, for counters in filters, it is necessary to exceed this limitation. It is therefore possible to deactivate this limit by configuration (see tag rest_api_aggs_nolimit ). In this case the absolute maximum is 2,147,483,647.

Maximum for children

The operation for lists of resources linked to the main resource (the size of $children for a multiple link property) is the same as for the maximum number of resources in a list. To change the value, the parameter is maxchildren instead of max.

To get the next ones, you have to use the children end point, using the after or before parameters

The $moreChildren_<propertyname> section (where propertyname is the name of the property) indicates the property's own link section, with counters, tokens (after and before) and HATEOAS links to the children end point. See response sample.

Headers

There are two sections of headers: the section describing the type of resource and the section describing the properties of the resource.

There are three ways to get the headers:

• per query parameter

• by a specific end point, of URI /api/rest/{type of service}{/resource name}/headers

• by the service type catalog

Request parameters

The possible parameters are

• headers: the default value (a boolean) for the other header parameters.
  If this parameter is not specified in the query, the default value for each other parameter depends on the end point. By default, the headers necessary for the use of the service are automatically selected. Resource headers are almost always exported and you will have to disable them explicitly to not get them (by rscHeaders=false). For the others, we will generally have the headers of properties and aggregates for the lists, the headers concerning the modification and the creation for the corresponding end point, etc.
  For the end point "headers", by default, we export all of them and it will be necessary to deactivate explicitly those we do not want by the corresponding parameter.

• rscHeaders: resource headers.

• dataHeaders: resource properties headers. Also enables the export of some property-related header information in the resource header section

• aggHeaders: aggregates headers.

• updateHeaders: creation and modification headers.

Information in the headers

Resource headers

In the response to services, we obtain the following information about the type of resource:

• a reminder of the name of the resource

• the localized name of the resource (human readable)

In addition in the headers, we get

• if dataHeaders is true

  • tree: true if the resource is tree-like (tree or thesaurus)

  • treefield: if tree is true, the name of the pivot property

  • If versions (notion of working copy) are requested (parameters withVersions or withVersionData), and the resource type supports working copy, then we have a $version property, whose value is a JSON object, with the following properties

    • archivedstatus, the description of the "archived" state

    • onlinestatus, the description of the "on line" state

• if rscHeaders is true

  • read: true, if the type of resource allows read end point (get a resource by identifier)

  • list: true, if the type of resource allows list end points (get a resource list, or tree)

  • update: true, if the type of resource allows updates

  • create: true, if the type of resource allows creations

  • createOrUpdate: true, if the resource type has the "create or update" mode configured

  • delete: true, if the type of resource allows deletions

  • workflow: true, if the type of resource allows workflows

  • workcopy: true, if the type of resource supports versions (work copy)

  • in the context of a catalog, for a resource of the DAM service, we also obtain

    • damAsset: true, if the type of resource is an asset library

    • damType: the DAM type of resource

      • asset, if the type of resource is an asset library

      • thesaurus, if the type of resource is a thesaurus

      • tree, if the type of resource is a tree

      • standard, if the type of resource is not particular (could be a list of values)

      • hidden, if the resource is bad configured, unuseable, etc

      • unknown, if the type cannot be determined

Resource properties headers

The headers section describes the list of available properties, and their description. For link properties, we will recursively have the description of the type of linked resource. This section is a JSON object, each field of which is the name of a property exported for a resource (dataHeaders), editable (updateHeaders), or exported in the data section of the aggregate counters (aggHeaders).

For each property, we will find:

• name, the localized name of the property (could be null for a parent reference property)

• taborder, the position of the corresponding field in an input form

• If the property is internationalized, or the translation of an internationalized property:

  • i18n: true if the property is internationalized

  • i18nFor: the name of the corresponding internationalized property, or null if the field is an internationalized property

  • i18nLocale: the locale of the field

• exported: true, if the property will be exported by default in a resource (by identifier, in a list, etc)

• indexed: true, if the property is indexed

• type: the type of property (a JSON type, extended to some additional values)

  • boolean: if the property is of boolean type

  • number: if the property is of number type

  • string: if the property is of string type
    the property can be exported as embedded JSON (in this case, it is necessary to consult the headers texttype and json to know how to read this property (see below))

  • object: if the property is a link to another resource (single link), or a parent reference property

  • tree: if the property is a tree pivot

  • array: if the type of property is a link to another resource (multiple linl) or a collection

  • isodate: if the type is date, and the date export mode is ISO (parameter dateIso8601 (or dateRFC3339)

  • isodatetime: if the type is datetime, and the date export mode is ISO (parameter dateIso8601 (or dateRFC3339)

  • timestamp: if the type is date or datetime, and the date export mode is not ISO (parameter dateIso8601 (or dateRFC3339))

  • resource: if the property is of file or image type

  • password: if the property is of password type (a string, always ****)

  • separator: if the property is a separator

• tree: true, if the type is tree, or if the linked resource is a tree (or a thesaurus)

• cluster: true, if the type is collection, and the corresponding resource can be exported as cluster of resources

• optionally if the type of property is string

  • text: true if the type is long text or html

  • maxlength: the maximum number of characters, or -1 if there is no limit, or it is not determinable

  • nullIfEmpty: true if an empty value is store as null

  • if text is true, additional headers are available

    • texttype: the type of text

      • HTML, if text contains HTML

      • JSON, if text contains JSON

      • PLAIN, if long text

      • TEXT, in any other cases (ie data/word, sentence for the technical type names)

      • NONE, if can’t be determined

    • replaceCR: if a carriare return (character \n) should be replaced with a <br> in a list display

    • html: true, if the text contains HTML

    • optionally, if texttype is JSON,

      • json: true, if the value is exported as JSON, not as text

• optionally if the type of property is link to another resource

  • href: the API end point URI base to get the resource

  • properties: a JSON object that describes the list of headers of the linked resource type

• group: the description of property group (delimits a set of properties that will be displayed together, in a tab for example). Can be null if no property group is defined.

  • id: a group id (properties that have the same group id are part of the same group)

  • name: the title of the group

• cud: available if parameter updateHeaders is true, describes the Creation, Update and Delete headers in a JSON object, with these properties:

  • key: true if the property is a key for create or update mode

  • update: true if the property is updatable

  • create: true, if the property is modifiable by value in a create or update process, or if the property is a collection, and it's possible to add collection items

  • delete: true, if the property is a collection, and it's possible to remove collection items

  • childrenAllowedUpdateModes: in the case of a property that designates a multiple link to another type of resource, lists the available modification modes

    • REPLACE:

    • MAP

    • APPEND

    • REMOVE

    • RETAIN

    • APPENDNEW

    • REMOVEFIRST

    • REMOVELAST

    • CLEAR

    • MULTIPLE

  • if the property is modifiable, and it is not a collection

    • mandatoryStructure, true if the property is configured as mandatory

    • mandatoryCreate, true if the property is set as mandatory to be provided as a parameter to a creation

    • mandatoryUpdate, true if the property is set as mandatory to be provided as a parameter to a modification (PUT)

    • mandatoryPatch, true if the property is set as mandatory to be provided as a parameter to a partial modification (PATCH)

    • defaultStructure, the default value (always a string) from structure configuration

    • defaultCreate, the default value for creation from resource configuration

    • defaultUpdate, the default value for modification from resource configuration

    • defaultPatch, the default value for partial modification from resource configuration

  • if the property is a file or an image, and update is true, and a maximum uploadable size value is configured

    • uploadMaxKibi: the maximum number of kibibytes (KiB=1024 bytes) to download

Additional headers may be available for certain types of services (for example, for mass import services)

Aggregates headers

Aggregate headers have the same form as resource property headers and are listed in the same section.

Creation and modification headers

These headers have the same form as the resource property headers and are listed in the same section. Additional information specific to modification and creation is added.

Additional data and technical information

You can get additional information to the resource metadata by using dedicated parameters.

Facets / faces

The facets describe the behavior of the metadata entry fields in the current state of the resource. This allows for example to have editable or mandatory fields, depending on the value entered in another field.

The facets information is boolean:

• mandatory: true if the property is mandatory (in a form, the property will be required)

• editable: true if the property is editable (it will remain modifiable, but in a form, we should not be able to edit its value)

• viewable: true if the property is viewable (the property should not be displayed in a form to edit the resource metadata or a view of the resource metadata)

Get facets information

Use the boolean parameter withFacets to true to get the facet information.

You will then get for each resource, the property $faces whose value is a JSON object, with for each resource property, a JSON object, a JSON object that describes the facets of this property with these boolean properties:

• viewable: if true, for the current values of the resource's metadata, the property is viewable

• editable: if true, for the current values of the resource's metadata, the property is editable

• mandatory: if true, for the current values of the resource's metadata, the property is required

• structureEditable: if true, the property is editable in the configuration of the objet in database

• structureMandatory: if true, the property is mandatory in the configuration of the objet in database

Old deprecated version

This facet data format is called version 2. Originally, the format was slightly different. For each resource property, there was a property with the same name prefixed by $faces-. For example, the face information of the property name was described by the value of the property $faces-name. This way of exposing the faces is called version 1.

To know which version is activated, consult the configuration by the service described in the chapter . You can find the version at path $.versions.$faces, in the form V1 or V2, depending on whether version 1 or version 2 is activated. You can also choose the version you want with the parameter facetsVersion. For example facetsVersion=1 (or facetsVersion=V1), to get the information in version 1 format.

Get the faces for a future version of metadata

If you need to know the facets for metadata values without saving them first, use the create or modify service in simulation mode. See the doc...

Get resources by applying facets

You can request a resource by applying the facets, which will disable the exposure of non-viewable properties according to the facets. For this, use the parameter facets.

status and workflow actions

You can obtain the possible actions for changing the workflow state for each resource with the parameter workflows=true. The section that lists the workflow actions is then in the $workflowActions property. See

to get description of this section.

Versions (workcopy)

When the resource supports the notion of working copy, we always get the current version of a resource (the working version) by default (look at the resource headers to see if working copy is supported).

The parameter withVersions=true will add to each resource a section in the property $versions the list of versions, as an array where each version is a JSON object with the following properties:

• id, the identifier of the resource

• $uuid, the unique identifier of the resource

• version, the version of the resource (an integer)

• $href, the URI to get the resource through the API by identifier

• $hrefUUID, the URI to get the resource through the API by unique identifier

The parameter withVersionData=true allows to expose the resources in the form they would have by a direct access.

When a resource is of the working copy type, we can obtain all the resources in a list, without taking this notion into account, by using the parameter queryVersions=false .

Accessing a new work copy

To get the working copy of a resource (and create it if it doesn't exist), use the following end point:

• verb: GET

• general form of the URI: /api/rest/{type of service}{/name of the resource type}/{id}/workcopy

Rights

You can find out what rights the current user has on each resource, in particular whether he has the right to modify or delete the resource.

Quick access

The following parameters allow a quick test of the modification and deletion rights:

• withEditRights: to be set to "true" to get the right to modify. The $canEdit property will be returned true if the user has the right to modify the resource, false otherwise

• withDeleteRights: to be set to "true" to get the right to delete. The $canDelete property will be returned true if the user has the right to modify the resource, false otherwise

The default value of these parameters is false, unless the withRights parameter is passed: it then sets the default value. So you just have to pass withRights=true to get both $canEdit and $canDelete.

If the value of the parameter is deep (instead of true), then we get the rights on the linked resources as well. The inheritance of the value of withRights to withEditRights and withDeleteRights is the same. If the value is explicitly specified, then the inheritance is cancelled. For example withRights=deep&withDeleteRights=true will give you modify rights on all resources, including those linked to properties of those resources, but delete rights only on resources of the main type.

Testing domains and actions

The rscSecurity parameter allows to get the rights on the resources types, as for example, if the current user has the right to create a resource of the current type. The security parameter allows to get the rights on the resources, like for example the right to modify a particular resource.

These parameters not only allow to test the standard CRUD rights, but also the specific domains and actions created specifically.

The parameter value (the parameter can have several values to test several actions) is composed of two parts, separated by a slash (/):

• the first part is the domain name. It is optional: if it is omitted, we will test the objectdata domain. For example, objectdata/insert, or insert allows to test the right to create

• the second part the name of the action

The value of a parameter can be a comma separated list of fields/actions. Thus security=update,delete is equivalent to security=update&security=delete.

Variations

Variations are the different versions available of the same binary media (preview, wartermarked asset, low resolution, square version...).

Parameters variations and players

The parameter variations is used to retrieve the list of existing variations for each resource. The parameter players parameter is used to retrieve the list of existing players for these variations.

These parameters can have the following values:

• true: to export the variations. In this case we just get a list (as a JSON array) of variation identifiers.

• false: the default value, so as not to export the variations.

• desc: the value to export

  • id: the variation identifier

  • name: the localized name

  • description: the localized description

• uri: the value to export in addition to what is exported for desc

  • uri: , the URI of variation

  • href: the URI of variation

• size: the value to export in addition to what is exported for desc

  • length: the file size in bytes

  • size: if relevant, a JSON object with

    • width: the width of image in pixels

    • height: the height of image in pixels

• content: the value to export in addition to what is exported for desc

  • contenttype: the content type

  • filesuffix: the file suffix (extension)

• all: the value to export all the information described above (in a JSON object)

Parameters variation and player

The parameter variation is used to indicate the list of variations (identifiers separated by commas) that we want to obtain.

The parameter player is used to indicate the list of players (identifiers separated by commas) that we want to obtain. If the parameter is missing and needed, the value of the parameter variation is used.

If the parameter variation is provided, we will also export for each resource a property variation that gives the identifier of the variation obtained by preferential choice in the indicated list (the first one that is available for the resource, in order from left to right). The same goes for the property player which will indicate the preferred player chosen in the parameter player.

Parameters variationFilter and playerFilter

The parameter variationFilter is only taken into account if the variation parameter is indicated. The parameter playerFilter is only taken into account if the player parameter is indicated. It is a boolean which when true indicates that we want to use the first matching variation (or player) of the associated list as a filter. In this case, the list of variations is not exported, but only the one that corresponds to this filter.

For example, with variation=poster,thumbnailSmall&variationFilter=true, we will get the poster variation description for assets that support this poster variation, otherwise we will get the thumbnailSmall variation.

Limitations

For services that return several resources (e.g. list), you can only get the list of variation identifiers (not the information for each variation), or only one variation (so use the filter mode).

Special case of mass import resources

Mass import services export specific information, which is described in the section dedicated to this service.