Browse for documents and assets
This describes the endpoint for browsing for items in the CMS. This is used for browsing documents, for example for cross-references, for document templates for new documents, and for browsing assets like images.
P OS T /browse
Browse for documents, templates or assets. May return folder and/or items of the specified types. This is a POST request instead of a GET request so the query object parameter can be extended with implementation specific attributes without hitting any query parameter limit constraints.
Parameters
body ( Required)
The body object containing the browse request.
Parameter type |
body |
Content type |
application/json |
body | |||
---|---|---|---|
parameter |
required |
type |
description |
context |
required |
Context |
The context from which the browse request was invoked. |
assetTypes |
required |
array[string] |
The types of content to browse. The only reserved types are 'document', 'document-template' and 'image'. For example this could be video, audio or any other implementation specific type. |
resultTypes |
required |
array[string] |
The types of items to return, can be one of:
|
folderId |
optional |
string |
The id of the folder to browse in, if none is specified, the root folder is meant. |
query |
optional |
Query |
Implementation dependent query object. |
limit |
optional |
number |
Paging option; The maximum number of results to return in this request. If not specified, return all results. |
offset |
optional |
number |
Paging option; The zero-based offset from on which to get results. If not specified, assume 0. |
Context | |||
---|---|---|---|
parameter |
required |
type |
description |
editSessionToken |
required |
string |
Uniquely identifies the instance of Fonto Editor. See Invocation of Fonto Editor for details. |
documentId |
optional |
string |
The id of the current document. |
Query | |||
---|---|---|---|
parameter |
required |
type |
description |
fulltext |
optional |
string |
Full text search query within the scope of the given folder and type. |
sort |
optional |
string |
The sort order to use, which can be implementation specific. |
Responses
Status code 200
A list of available items is returned.
body | |||
---|---|---|---|
parameter |
required |
type |
description |
totalItemCount |
required |
number |
The total number of results for the query. Can be higher than the number of returned items if pagination is used. |
items |
required |
array[BrowseItem] |
The result items. This list may be empty if the request does not match any items. |
metadata |
optional |
RootMetadata |
The implementation specific metadata describing the properties of the body. Some properties are reserved. For example see the hierarchy property that is already supported out-of-the-box below in RootMetadata. |
BrowseItem | |||
---|---|---|---|
parameter |
required |
type |
description |
id |
required |
string |
The target to use as link, href, source or id of the resource to load. |
label |
required |
string |
The label to use for displaying the resource. |
type |
required |
string |
The type of item, for example: folder, document, document-template, link, image, file or unknown. |
metadata |
optional |
ItemMetadata |
The implementation specific metadata describing the properties of this entry. See some cases that are already supported out-of-the-box below in ItemMetadata. |
RootMetadata | |||
---|---|---|---|
parameter |
required |
type |
description |
hierarchy |
optional |
array[BrowseItem] |
ItemMetadata | |||
---|---|---|---|
parameter |
required |
type |
description |
icon |
optional |
string |
Add a fontawesome icon if it needs to be a different than the default icon. The icon name must not include a prefix (fa-). For example 'folder-o' (default for type folder), 'file-text-o' (default for type document), 'file-image-o'(default for type image), 'file-o' (default for type document-template). |
isDisabled |
optional |
boolean |
If the item is disabled, the user can't select it. |
description |
optional |
string |
Is used to add an extra description to an item. Should only be used by a item with type 'document-template'. |
properties |
optional |
object |
Is used to describe properties by name for an item. Should only be used by a item with type 'image'. |
Status code 403
The user is not authorized to browse here.
Status code 404
The requested folder does not exist in the CMS. Should not be used if the query is valid but has no results.
Status code 500
Any error in the 500 range indicates a problem with the CMS.
Examples
Request
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
"referrerDocumentId": "076A86C7-BA00-4AC2-B363-37C454481183"
},
"assetTypes": [ "document" ],
"resultTypes": [ "file" ]
}
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
"referrerDocumentId": "076A86C7-BA00-4AC2-B363-37C454481183"
},
"assetTypes": [ "document" ],
"resultTypes": [ "folder" ],
"folderId": "74257961-EDE3-4180-AF17-0A435EE8FB7B"
}
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
"referrerDocumentId": "076A86C7-BA00-4AC2-B363-37C454481183"
},
"assetTypes": [ "document" ],
"resultTypes": [ "file" ],
"query": {
"fulltext": "CMS Connectors API"
}
}
JavaScript
{
"context": {
"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
"referrerDocumentId": "076A86C7-BA00-4AC2-B363-37C454481183"
},
"assetTypes": [ "image" ],
"resultTypes": [ "file" ],
"limit": 42,
"offset": 42
}
Response
JavaScript
{
"totalItemCount": 1,
"items": [
{
"id": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"label": "Dutchclogs.jpg",
"type": "image",
"metadata": {
"icon": "picture-o",
"isDisabled": true,
"properties": {
"width": "1",
"height": "1",
"fileSize": "1234 kb",
"created": "01-02-2003 12:34:56",
"tags": "first, second, third, everything-is-formatted-by-cms"
}
}
}
]
}
JavaScript
{
"totalItemCount": 1,
"items": [
{
"id": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"label": "Concept.template",
"type": "document-template",
"metadata": {
"icon": "file-code-o",
"isDisabled": true,
"description": "Concepts provide background that helps readers understand essential information about a product, a task, a process, or any other conceptual or descriptive information."
}
}
]
}
This case assumes the context.documentId is not set, the context.documentId is set to 'B457003F-37E3-4B46-9352-C5CCFB60C808'. The CMS finds the folder in which the document with documentId 'B457003F-37E3-4B46-9352-C5CCFB60C808' is found, and uses this folder as the folderId. It then returns the contents of this folder, along with the hierarchy of the folder ancestry.
JavaScript
{
"totalItemCount": 2,
"items": [
{
"id": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
"label": "glossary.xml",
"type": "document"
},
{
"id": "B457003F-37E3-4B46-9352-C5CCFB60C808",
"label": "clogs.xml",
"type": "document"
}
],
"metadata": {
"hierarchy": [
{
"id": "rootfolder-id",
"label": "Home",
"type": "folder"
},
{
"id": "33A8360B-520F-48D2-B8B0-BA7761A73565",
"label": "Documents",
"type": "folder"
}
]
}
}