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.

POST /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:

  • [ 'file' ]

  • [ 'folder' ]

  • [ 'file', 'folder' ]

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.

Accept (Required)

The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. See the MDN Web Docs for more information.

Parameter type

header

Type

string

Value

application/json

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",
		"documentId": "076A86C7-BA00-4AC2-B363-37C454481183"
	},
	"assetTypes": [ "document" ],
	"resultTypes": [ "file" ]
}

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
		"documentId": "076A86C7-BA00-4AC2-B363-37C454481183"
	},
	"assetTypes": [ "document" ],
	"resultTypes": [ "folder" ],
	"folderId": "74257961-EDE3-4180-AF17-0A435EE8FB7B"
}

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
		"documentId": "076A86C7-BA00-4AC2-B363-37C454481183"
	},
	"assetTypes": [ "document" ],
	"resultTypes": [ "file" ],
	"query": {
		"fulltext": "CMS Connectors API"
	}
}

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
		"documentId": "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"

			}
		]
	}
}