logoBack to home screen

Searching for Repository Contents via ADx REST API

Overview

ADx Repository API provides the following search endpoints (explained below in more detail):

  • https://[ADx_HOST]/tribefire-services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/search - for searching contents by their properties only (such as content name, owner or version).
  • https://[ADx_HOST]/tribefire-services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/search/by-condition - for searching contents using GMQL queries, which allows more depth and customization than searching by properties only.
  • https://[ADx_HOST]/tribefire-services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/search/by-text - for running fulltext search (searching for text inside the content).

Prerequisites

If you're going to use the fulltext search, the following criteria must be met:

  • Fulltext search is enabled on a repository.
  • Contents uploaded to the repository at a time when fulltext was disabled must be reindexed first.

Searching by Content Properties

This search request checks content properties and returns contents matching the property values in your request. All properties are sent in the request query.

Endpoint Description

Request typeService descriptionEndpointRequest query parametersForm dataReturns
GETSearch for contents using content propertieshttps://[ADx_HOST]/tribefire-services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/searchSee Parameters belowNoneList of contents matching the criteria

Parameters

You can add any of the following parameters to your query. Sending a call without any parameters will return all contents.

ParameterData typeDescription
sessionIdstringSession ID returned after authentication.
chronicalIdstringContent chronicalId property
createdBystringUser name of the content creator
entryTypestringEntry type (CONTENT or FOLDER)
includeVersionsbooleanInclude all versions in the response (true/false)?
isLockedbooleanIs the content currently locked (true/false)?
lastModifiedBystringUser name of the last user who modified the content.
lockedBystringUser name of the last user who locked the content.
mimeTypestringResource mime type
namestringContent name
ownerstringUser name of the content owner
parentIdstringID of the folder where the content is located.
tagsarray of stringsList of tags on the content
versionstringContent version
versionStatusstringContent status (WORKING_COPY, CURRENT)
orderBystringEnter any other property by which the content should be ordered (for example name, owner, version...)
orderingDirectionstringasc or desc
limitintegerSpecifies the maximum amount of search results returned.
offsetintegerSpecifies the offset of the search result.
includePropertiesarray of stringsIndicates which properties to include in the search results. See Querying for Specific Properties (Include and Exclude)
excludePropertiesarray of stringsIndicates which properties to exclude from the search results. See Querying for Specific Properties (Include and Exclude)
autoExcludebooleanIndicates whether some predefined properties (e.g.: virtual properties like Folder.children) should be automatically excluded. This can be overridden for specific properties by explicitly mentioning them in the includeProperties list.

cURL Example

The following call will return all contents where the owner is cortex and the version is 1.0:

curl --location --request GET 'https://[ADx_HOST]/services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/search?sessionId=[SESSION_ID]&owner=cortex&version=1.0' \
--header 'Content-Type: application/json'

A successful response from the server should be similar to the one below:

{
    "_type": "tribefire.adx.model.content.service.v1.request.crud.EntriesResponse",
    "count": 3,
    "duration": 57,
    "entries": [
        {
            "_type": "tribefire.adx.model.content.Content",
            "active": true,
            "chronicalId": "554b954b-cf71-4788-ab5c-82031ca3a539",
            "createdAt": "2020-09-07T11:43:45.347+0000",
            "createdBy": "cortex",
            "entryType": "CONTENT",
            "id": "554b954b-cf71-4788-ab5c-82031ca3a539",
            "lastModifiedAt": "2020-09-07T16:23:52.538+0000",
            "lastModifiedBy": "cortex",
            "lockedAt": "2020-09-07T16:24:00.417+0000",
            "lockedBy": "cortex",
            "name": "randomtext",
            "owner": "cortex",
            "parent": {
                "_type": "tribefire.adx.model.content.Folder",
                "active": true,
                "createdAt": "2020-09-07T12:30:20.693+0000",
                "createdBy": "cortex",
                "entryType": "FOLDER",
                "id": "bab07a13-b14a-41c9-b6c3-3a46e5e12ea7",
                "lastModifiedAt": "2020-09-07T12:30:20.693+0000",
                "lastModifiedBy": "cortex",
                "name": "test",
                "owner": "cortex",
                "partition": "access.adx.content.gk"
            },
            "partition": "access.adx.content.gk",
            "resource": {
                "_type": "com.braintribe.model.resource.Resource",
                "created": "2020-09-07T11:43:44.981+0000",
                "creator": "cortex",
                "fileSize": 53,
                "id": "67e52415-0706-4c17-baa7-b8934dc0e697",
                "md5": "87bfac4e23c66afa86fe8eebe6e68b52",
                "mimeType": "text/plain",
                "name": "randomtext.txt",
                "partition": "access.adx.content.gk",
                "resourceSource": {
                    "_type": "com.braintribe.model.resource.source.FileSystemSource",
                    "id": "db66c5c3-bfc6-429f-807d-92a094ede292",
                    "partition": "access.adx.content.gk",
                    "path": "2009/0711/4344/fdf58ffe-0e70-42c5-bec2-9082936ff27f"
                }
            },
            "version": "1.0",
            "versionStatus": "CURRENT"
        },
        {
            "_type": "tribefire.adx.model.content.Content",
            "active": true,
            "chronicalId": "554b954b-cf71-4788-ab5c-82031ca3a539",
            "createdAt": "2020-09-07T16:24:00.417+0000",
            "createdBy": "cortex",
            "entryType": "CONTENT",
            "id": "f44435bd-f66d-4b49-9c23-280c93d5846b",
            "lastModifiedAt": "2020-09-07T16:24:00.417+0000",
            "lastModifiedBy": "cortex",
            "lockedAt": "2020-09-07T16:24:00.417+0000",
            "lockedBy": "cortex",
            "name": "randomtext",
            "owner": "cortex",
            "parent": {
                "_type": "tribefire.adx.model.content.Folder",
                "active": true,
                "createdAt": "2020-09-07T12:30:20.693+0000",
                "createdBy": "cortex",
                "entryType": "FOLDER",
                "id": "bab07a13-b14a-41c9-b6c3-3a46e5e12ea7",
                "lastModifiedAt": "2020-09-07T12:30:20.693+0000",
                "lastModifiedBy": "cortex",
                "name": "test",
                "owner": "cortex",
                "partition": "access.adx.content.gk"
            },
            "partition": "access.adx.content.gk",
            "predecessor": {
                "_type": "tribefire.adx.model.content.Content",
                "active": true,
                "chronicalId": "554b954b-cf71-4788-ab5c-82031ca3a539",
                "createdAt": "2020-09-07T11:43:45.347+0000",
                "createdBy": "cortex",
                "entryType": "CONTENT",
                "id": "554b954b-cf71-4788-ab5c-82031ca3a539",
                "lastModifiedAt": "2020-09-07T16:23:52.538+0000",
                "lastModifiedBy": "cortex",
                "lockedAt": "2020-09-07T16:24:00.417+0000",
                "lockedBy": "cortex",
                "name": "randomtext",
                "owner": "cortex",
                "parent": {
                    "_type": "tribefire.adx.model.content.Folder",
                    "active": true,
                    "createdAt": "2020-09-07T12:30:20.693+0000",
                    "createdBy": "cortex",
                    "entryType": "FOLDER",
                    "id": "bab07a13-b14a-41c9-b6c3-3a46e5e12ea7",
                    "lastModifiedAt": "2020-09-07T12:30:20.693+0000",
                    "lastModifiedBy": "cortex",
                    "name": "test",
                    "owner": "cortex",
                    "partition": "access.adx.content.gk"
                },
                "partition": "access.adx.content.gk",
                "resource": {
                    "_type": "com.braintribe.model.resource.Resource",
                    "created": "2020-09-07T11:43:44.981+0000",
                    "creator": "cortex",
                    "fileSize": 53,
                    "id": "67e52415-0706-4c17-baa7-b8934dc0e697",
                    "md5": "87bfac4e23c66afa86fe8eebe6e68b52",
                    "mimeType": "text/plain",
                    "name": "randomtext.txt",
                    "partition": "access.adx.content.gk",
                    "resourceSource": {
                        "_type": "com.braintribe.model.resource.source.FileSystemSource",
                        "id": "db66c5c3-bfc6-429f-807d-92a094ede292",
                        "partition": "access.adx.content.gk",
                        "path": "2009/0711/4344/fdf58ffe-0e70-42c5-bec2-9082936ff27f"
                    }
                },
                "version": "1.0",
                "versionStatus": "CURRENT"
            },
            "resource": {
                "_type": "com.braintribe.model.resource.Resource",
                "created": "2020-09-07T16:24:00.514+0000",
                "creator": "cortex",
                "fileSize": 53,
                "id": "f2e11918-ff5a-4fe9-bb05-8f60b9d635dd",
                "md5": "87bfac4e23c66afa86fe8eebe6e68b52",
                "mimeType": "text/plain",
                "name": "randomtext.txt",
                "partition": "access.adx.content.gk",
                "resourceSource": {
                    "_type": "com.braintribe.model.resource.source.FileSystemSource",
                    "id": "87ea935d-dc9b-4b50-adff-35737c586414",
                    "partition": "access.adx.content.gk",
                    "path": "2009/0716/2400/745fb59f-ce08-49b0-a0d4-35a826031953"
                }
            },
            "version": "1.0",
            "versionStatus": "WORKING_COPY"
        },
        {
            "_type": "tribefire.adx.model.content.Content",
            "active": true,
            "chronicalId": "2dd93adf-9802-412c-a0df-0261a5e0f1b1",
            "createdAt": "2020-09-07T11:58:54.477+0000",
            "createdBy": "cortex",
            "entryType": "CONTENT",
            "id": "2dd93adf-9802-412c-a0df-0261a5e0f1b1",
            "lastModifiedAt": "2020-09-07T11:58:54.478+0000",
            "lastModifiedBy": "cortex",
            "name": "text",
            "owner": "cortex",
            "partition": "access.adx.content.gk",
            "resource": {
                "_type": "com.braintribe.model.resource.Resource",
                "created": "2020-09-07T11:58:54.125+0000",
                "creator": "cortex",
                "fileSize": 4,
                "id": "58501f80-b61f-423a-a135-74ab416e16bc",
                "md5": "1cb251ec0d568de6a929b520c4aed8d1",
                "mimeType": "text/plain",
                "name": "text.txt",
                "partition": "access.adx.content.gk",
                "resourceSource": {
                    "_type": "com.braintribe.model.resource.source.FileSystemSource",
                    "id": "55f112c8-5ce0-4f5d-9242-5a8e5ae2f40f",
                    "partition": "access.adx.content.gk",
                    "path": "2009/0711/5854/cfda7913-088e-48a7-9a68-9a74a3758dce"
                }
            },
            "version": "1.0",
            "versionStatus": "WORKING_COPY"
        }
    ]
}

Searching by Condition

This search request returns contents based on criteria defined by a GMQL statement (check the simple examples below or read about GMQL WHERE in detail.

Constructing GMQL Statements

ADx Content has the following structure, where almost all properties are of the string type:

"_type": "tribefire.adx.model.content.Content",
            "active": true,
            "chronicalId": "554b954b-cf71-4788-ab5c-82031ca3a539",
            "createdAt": "2020-09-07T11:43:45.347+0000",
            "createdBy": "cortex",
            "entryType": "CONTENT",
            "id": "554b954b-cf71-4788-ab5c-82031ca3a539",
            "lastModifiedAt": "2020-09-07T16:23:52.538+0000",
            "lastModifiedBy": "cortex",
            "lockedAt": "2020-09-07T16:24:00.417+0000",
            "lockedBy": "cortex",
            "name": "randomtext",
            "owner": "cortex",
            "parent": {
                "_type": "tribefire.adx.model.content.Folder",
                "active": true,
                "createdAt": "2020-09-07T12:30:20.693+0000",
                "createdBy": "cortex",
                "entryType": "FOLDER",
                "id": "bab07a13-b14a-41c9-b6c3-3a46e5e12ea7",
                "lastModifiedAt": "2020-09-07T12:30:20.693+0000",
                "lastModifiedBy": "cortex",
                "name": "test",
                "owner": "cortex",
                "partition": "access.adx.content.gk"
            },
            "partition": "access.adx.content.gk",
            "resource": {
                "_type": "com.braintribe.model.resource.Resource",
                "created": "2020-09-07T11:43:44.981+0000",
                "creator": "cortex",
                "fileSize": 53,
                "id": "67e52415-0706-4c17-baa7-b8934dc0e697",
                "md5": "87bfac4e23c66afa86fe8eebe6e68b52",
                "mimeType": "text/plain",
                "name": "randomtext.txt",
                "partition": "access.adx.content.gk",
                "resourceSource": {
                    "_type": "com.braintribe.model.resource.source.FileSystemSource",
                    "id": "db66c5c3-bfc6-429f-807d-92a094ede292",
                    "partition": "access.adx.content.gk",
                    "path": "2009/0711/4344/fdf58ffe-0e70-42c5-bec2-9082936ff27f"
                }
            },
            "version": "1.0",
            "versionStatus": "CURRENT"
        }

Note that certain properties are parts of a collection, such as parent or resource. This is where GMQL queries become useful - they allow you to query for properties inside such collection. Since almost all properties are of the string type, using the like and = operators, as shown below, should cover all cases.

GMQL Syntax

Follow the syntax below when constructing your queries:

property like 'value' and collection.property='value'

In more specific terms (for content name starting with foo inside the test folder):

name like 'foo*' and parent.name='test'

Including fulltext search inside the content:

name like 'foo*' and parent.name = 'test' and fullText('TEXT')

GMQL Operators

OperatorDescriptionExample
inThe operator in is used to compare one value against a set of values contained in a collection. If the value provided is contained within this collection the entity instance will be returned as part of the results set. The value is provided on the left-half side of the operator while the set is provided on the right-hand side.
There are two specific ways that this operator can be used. You can either use this operator to search a collection property for the value defined, or you search on a specific property for one of several values passed as a set.
Compare a value against those contained in a collection property (return only Person instances which have Smith contained in its collection property nicknames): select * from com.braintribe.custom.model.Person where "Smith" in nicknames
or for complex collections (that is, collections whose elements are other entities) (return only User instances that contain the role john.smith.role.b in their collection property roles: select * from com.braintribe.model.user.User u where reference(com.braintribe.model.user.Role, 'john.smith.role.b') in u.roles
Compare a property of an entity against a collection of values (return only User entities that have the second name of either Cortex or Smith): select * from com.braintribe.model.user.User u where u.secondName in ('Cortex', 'Smith')
4 in favouriteNumbers
secondName in ('Cortex', Smith')
likeUsed in string comparisons. For example, firstName like "Rob" returns any instance where the string value matches exactly the value given. In the case of the example only Rob is returned, not Robert. If you wish to match partial strings, you must use the * wildcard. For example, firstName like "Rob*" returns both Rob and Robert.secondName like 'Cortex'
ilikeUsed for non case-sensitive comparisons. The functionality of ilike depends on the underlying repository that is connected to the Access. If you use SMOOD database, the ilike operator is available by default.secondName ilike 'Cortex'
>=greater than or equal to
>greater than
!=not equal to
<less than
<=less than or equal to
=Whether the left-hand value equals the right-hand value

Endpoint Description

Request typeService descriptionEndpointRequest query parametersForm dataReturns
GETSearch for contents using a GMQL conditionhttps://[ADx_HOST]/tribefire-services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/search/by-conditionSee Parameters belowNoneList of contents matching the GMQL query criteria.

Parameters

ParameterData typeDescription
sessionIdstringSession ID returned after authentication.
conditionstringGMQL WHERE statement querying for any valid content property.
entryTypestringEntry type (CONTENT or FOLDER)
includeVersionsbooleanInclude all versions in the response (true/false)?
orderBystringEnter any other property by which the content should be ordered (for example name, owner, version...)
orderingDirectionstringasc or desc
limitintegerSpecifies the maximum amount of search results returned.
offsetintegerSpecifies the offset of the search result.
includePropertiesarray of stringsIndicates which properties to include in the search results. See Querying for Specific Properties (Include and Exclude)
excludePropertiesarray of stringsIndicates which properties to exclude from the search results. See Querying for Specific Properties (Include and Exclude)
autoExcludebooleanIndicates whether some predefined properties (e.g.: virtual properties like Folder.children) should be automatically excluded. This can be overridden for specific properties by explicitly mentioning them in the includeProperties list.

cURL Example

Assuming our requirement is to find all contents with a name starting with foo and stored in a folder called test, we can write the following condition:

name like 'foo*' and parent.name='test'

Note that in this case, when querying for a property which is part of a collection (applies to parent, resource or predecessor), you need to use the following syntax: parent.property (for example parent.id, resource.mimeType or predecessor.parent.name).

We can send the following request:

curl --location --request GET 'https://[ADx_HOST]/tribefire-services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/search/by-condition?condition=name%20like%20%27foo*%27%20and%20parent.name=%27test%27&sessionId=[SESSION_ID]' \
--header 'Content-Type: application/json'

The response should be a list of contents matching your criteria.

Searching by Text

This search request returns all contents where a specific text can be found.

Endpoint Description

Request typeService descriptionEndpointRequest query parametersForm dataReturns
GETSearch for contents using a GMQL conditionhttps://[ADx_HOST]/tribefire-services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/search/by-textSee Parameters belowNoneList of contents containing the provided text.

Parameters

ParameterData typeDescription
sessionIdstringSession ID returned after authentication.
searchTextstringText you want to find in contents.
entryTypestringEntry type (CONTENT or FOLDER)
includeVersionsbooleanInclude all versions in the response (true/false)?
orderBystringEnter any other property by which the content should be ordered (for example name, owner, version...)
orderingDirectionstringasc or desc
limitintegerSpecifies the maximum amount of search results returned.
offsetintegerSpecifies the offset of the search result.
includePropertiesarray of stringsIndicates which properties to include in the search results. See Querying for Specific Properties (Include and Exclude)
excludePropertiesarray of stringsIndicates which properties to exclude from the search results. See Querying for Specific Properties (Include and Exclude)
autoExcludebooleanIndicates whether some predefined properties (e.g.: virtual properties like Folder.children) should be automatically excluded. This can be overridden for specific properties by explicitly mentioning them in the includeProperties list.

cURL Example

To search for the word text, send the following call:

curl --location --request GET 'https://[ADx_HOST]/tribefire-services/api/v1/access.adx.content.[REPOSITORY_NAME]/v1/content/search/by-text?sessionId=[SESSION_ID]&searchText=text' \
--header 'Content-Type: application/json'

The response should be a list of contents matching your criteria.