See examples and a sample resource here.
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 DAM & DATA API 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.
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.
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 /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 /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.
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}
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.
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):
"links": {
"moreResultsToken": "a9b312e9f7e0270b5bf16573ec32eb8f",
"nextResultsToken": "a9b312e9f7e0270b5bf16573ec32eb8f",
"previousResultsToken": null,
"href": "https://club-wed.wedia-group.com/api/rest/dam/data/asset",
"previous": null,
"next": "https://club-wed.wedia-group.com/api/rest/dam/data/asset?after=a9b312e9f7e0270b5bf16573ec32eb8f",
"more": "https://club-wed.wedia-group.com/api/rest/dam/data/asset?after=a9b312e9f7e0270b5bf16573ec32eb8f"
} |
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.
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):
"links": {
"href": "https://club-wed.wedia-group.com/api/rest/dam/data/asset/list",
"first": "https://club-wed.wedia-group.com/api/rest/dam/data/asset/list?from=1&max=50",
"previous": null,
"next": "https://club-wed.wedia-group.com/api/rest/dam/data/asset/list?from=51&max=50",
"last": null
} |
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}
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)
This service allows to use the lists in order to obtain trees, which makes it possible to benefit from all the possibilities of the lists to obtain a tree. On the other hand, the calculations can be very long, especially for very large trees. In this case, it is preferable to use the optimized tree service which has much less options but is much faster. In particular, use it when filling in selection lists or filters. |
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.
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
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 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.
By default, the depth is 0, so you will only get the first level of the tree. Use this parameter to get more. For example, to get all the levels, |
See a sample resource here.
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 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.
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".
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.
Specify the phrase you are looking for in the find parameter.
The parameter find is not supported by the service for accessing a resource by its identifier.
The parameter find is not supported by the service for accessing a resource by its identifier.
For the optimized tree service, the |
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
It is possible to search by criteria, using the query parameter. The syntax of this parameter is described in the Request Language 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"}.
Using these suffixed parameters is essential when a criterion uses a property specific to one type of resource that does not exist in the others. |
Note that services can be configured to give access to only part of the existing resources. It is not possible with this parameter to extend the set of accessible resources, only to restrict it.
Note that services can be configured to give access to only part of the existing resources. It is not possible with this parameter to extend the set of accessible resources, only to restrict it.
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)
The optimized tree service allows only one sorting criteria |
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
It is of course possible to combine the two types of search in the same query.
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 (Property filters and selection) 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 (Filtering technical properties) or Swagger API documentation.
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).
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.
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.
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
…
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.
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.
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 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).
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.
aggNotAssigned
aggTreeCount
aggMinOccurs
sortAggsOnName and aggSortFieldnames
aggSortFieldnames
sortAggsOnName
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.
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).
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)
Note that when no value is assigned to the field, the data section always presents only an id at 0, whatever the configuration and the aggfields parameter.
Note that when no value is assigned to the field, the data section always presents only an id at 0, whatever the configuration and the aggfields parameter.
See more details here.
See the documentation to get binaries
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).
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
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).
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.
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
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.
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.
Since
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.
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.
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.
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.
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)
There are different ways to describe a grouping.
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:
{
"prop": "assetnature"
} |
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:
{
"type": "assetkeyword"
} |
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.
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.
This string will be considered as a metadata UUID You can also use an array of strings to indicate several UUIDs.
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).
To summarize, the response/data section of the main query is an array of sections (JSON Object) made up as follows:
in groupData property, an object to describe the group
in data property, an array with the asset (or any other data) corresponding to the group (having the corresponding metadata)
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
some additional data
total: the total number of data that can be obtained for this group
count: the number of data obtained in this response
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)
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
groupId, the ID of the group
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
total: the total number of group instances (metadata instances) for this group
count: the number of group instances for this group in the current response
complete: true if all the group instances have been obtained
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.
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:
{
groups: {
location: {
prop: location
},
autor: {
prop: photograph,
max: 4
}
}
} |
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:
{
"response": {
"data": [
{
"groupdata": { // DATA of group "location" for instance assetgeography/11
"groupId": location,
"data": { // DATA describing the instance assetgeography/11
"id": 11,
"$uuid": "783if7sieq1dun6m5bt9p1k8uafr1p93eocgqro",
"name": "Latin America and the Caribbean"
},
"count": 3, // this means this block contains 3 assets
"total": 10, // this means there are 10 assets with the location assetgeography/11
"nextToken": ...,
"nextData": {
"groups": {
"location": {
"prop": "location",
"id": "783if7sieq1dun6m5bt9p1k8uafr1p93eocgqro",
"dataAfter": "91e8ea74d51d412115659a2abc7910fe"
}
}
},
"complete": false // all asset for assetgeography/11 hasn't been get (only 3/10)
},
"data": [ 3 assets with location=assetgeography/11: rnipqec3pw1uh83wrpwtp7ni4w, f1cxjquj5riabqtrji8oh5qbdh, f1cxjquj5riabtmwgib68i5w5w ]
},
{
"groupdata": // DATA of group "location" for instance assetgeography/13
},
// then 10 others (for location)
{
"groupdata": { // then now, DATA of group "photo" for instance assetauthor/78
"groupId"; "author",
"data": { // DATA describing the instance assetauthor/78
"id": 78
},
"count": 1,
"total": 1,
"nextToken": null,
"nextData": null // there is no more asset for this photographer
"complete": true
}
},
then 19 others (for author)
],
"groups": [ // a summary of each group
{
"groupId": "location",
"count": 12, // we got 12
"total": 12, // there are 12 to get
"nextToken": null,
"nextGroup": null,
"complete": true // we get all involved instances of assetgeography
},
{
"groupId": "author",
"count": 20, // we got 20
"total": 97, // there are 97 to get
"nextToken": ...,
"nextGroups": {
"groups": {
"author": {
"prop": "photograph",
"max": 4,
"groupAfter": "ny8ig5b584wotcasfwh57mezjy"
}
}
},
"complete": false // we don't get all involved instances of "assetauthor"
}
]
}
} |
Let’s have a look to nextData just above:
{
"groups": {
"location": {
"prop": "location",
"id": "783if7sieq1dun6m5bt9p1k8uafr1p93eocgqro",
"dataAfter": "91e8ea74d51d412115659a2abc7910fe"
}
} |
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).
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)
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.
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.
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 ). In this case the absolute maximum is 2,147,483,647.
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.
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
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.
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 the response to a multi-resource service invocation, we obtain in the resources property a JSON array that lists all the descriptions of each resource
In the response to a multi-resource service invocation, we obtain in the resources property a JSON array that lists all the descriptions of each resource
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
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)
Aggregate headers have the same form as resource property headers and are listed in the same section.
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.
You can get additional information to the resource metadata by using dedicated parameters.
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)
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
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 Get Server and REST API configuration . 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.
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...
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.
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
Workflows (change status, or get possible workflow actions) to get description of this section.
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 .
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
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.
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.
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 are the different versions available of the same binary media (preview, wartermarked asset, low resolution, square version...).
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)
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.
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.
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).
Mass import services export specific information, which is described in the section dedicated to this service.