Filtering technical properties

Owned by Joël DRIGO
Last updated: Feb 16, 2022
2 min read

The techprops parameter allows, when obtaining a resource via the REST API, to select the technical properties that we want to obtain. Technical properties are properties whose name begins with the $ character. There are two categories:

  • technical properties exported on demand, by certain parameters passed at the invocation of the end point

  • technical properties exported by default

The techprops parameter only allows to filter the properties exported by default. The $uuid property is not filterable (it is always exported when the id is exported).

Syntax

  • the parameter value is the list of properties we want to see, as a comma-separated list of property names

  • property names may not be prefixed with the $ character in the list

  • some properties with the same name being used in different contexts, or some technical properties not having a name starting with $, there is a specific name usable for filtering (see the list of these properties below)

  • if techprops is passed as a parameter with a value, it is active. If it is not supplied, all default properties are exported

  • you can explicitly filter (not export) a property by putting - in front. You can put + in front of it, but it's not useful, it's like putting nothing (in other words, it's + by default)

  • There are properties that are exported implicitly, even if you filter them. You have to filter them explicitly to avoid exporting them. These are the

    • $resource

    • $assetHash

  • the word all (without the character $ in front) is equivalent to the list of all properties, in inclusive mode and can be included in a list

    • all means that everything is included, except what is explicitly excluded

    • -all means that everything is excluded, except what is explicitly included

    • techprops=all is equivalent to no techprops parameter

  • the word none (without the character $ in front) is equivalent to the list of all properties, in exclusive mode and can only be used alone

    • none means that no property will be exported except the implicit properties

    • in a list, none is ignored

  • to include a property that is in an object that is a technical property value, it may be necessary for it to be included. For example, $preview.href denotes the property of a JSON object that is the value of the technical property $preview. To include this property in the response, it is necessary to pass techprops=-all,$preview.href,$preview

  • an excluded property cannot be included (exclusion has priority over inclusion)

Examples

  • techprops=-all: you'll get only $uuid (always included, if id is present)

  • techprops=all,-href: you’ll get all properties, except $href (excluded because of -href) and $hrefUUID (excluded because $href is excluded)

  • techprops=none: you’ll get $uuid(always included, if id is present), $assetHash(implicitly included)

  • techprops=none,+href: you’ll get $uuid, $assetHash, $href(excluded because of +href), $hrefUUID (included because $href is included)

  • techprops=-all,$preview.href,$preview: you’ll get $uuid, $preview.url (included because of $preview), $preview.href (included because of $preview.href, and $preview)

  • techprops=$preview.href,$preview: you’ll get $uuid(always included, if id is present), $assetHash(implicitly included), $preview.url (included because of $preview), $preview.href (included because of $preview.href, and $preview)

List of extended names

  • $image.$type: image or file type ($type property in an image or file property)

  • $image.$mimetype: mimetype of image or file (property $mimetype in an image or file property)

  • $image.$href

  • $image.remoteURL

  • $image.localURL

  • $image.thumbnailSmall

  • $image.thumbnailSmallLocalURL

  • $image.thumbnailSmallRemoteURL

  • $reference.$score

  • $suggestion.$score

  • $preview.href: (need also $preview)

  • $suggestion.$href

  • $resource.$href

  • $treeancestor

  • $treeancestor.$resource

 

Â