REST API for Documents

Get File Assigned Metadata Collections

get

/documents/api/1.2/files/{fileId}/metadataFields

Get field definitions of all fields in a specified metadata collection assigned to a particular file or its own parent folder hierarchy.

Request

Supported Media Types

application/json
application/xml

Path Parameters

fileId: string

Globally unique identifier (GUID) for the file.

Query Parameters

directAssigned(optional): string

Specify if just directly assigned collections should be retrieved (1) or if all inherited collections should be included as well (0).

Header Parameters

accessToken(optional): string

Applink access token authorizing the current user to access the parent folder or this file. This parameter is mandatory if appLinkID is used. It can be used as accessToken or AccessToken.
appLinkID(optional): string

Applink ID authorizing the current user to access the parent folder or this file. Any time the parameter appLinkID is used, a parameter accessToken must be provided as well. It can be used as appLinkID or AppLinkID.

Response

Supported Media Types

application/json
application/xml

200 Response

The request was fulfilled.

Root Schema : FileGetAssignedCollectionResponse

Type: object

The response body includes information about the get assigned collections operation.

Show Source

errorCode(optional): number

An error code of zero (0) indicates no errors.
idList(optional): string

Globally unique identifier (GUID) of the original file.
metadataFields(optional): array metadataFields
type(optional): string

Item type file.

{
    "description":"The response body includes information about the get assigned collections operation.",
    "properties":{
        "idList":{
            "type":"string",
            "description":"Globally unique identifier (GUID) of the original file."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>file</code>."
        },
        "errorCode":{
            "type":"number",
            "description":"An error code of zero (0) indicates no errors."
        },
        "metadataFields":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/CollectionDefinition"
            }
        }
    }
}

Nested Schema : metadataFields

Type: array

Show Source

Array of: object CollectionDefinition

Metadata collection definition.

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/CollectionDefinition"
    }
}

Nested Schema : CollectionDefinition

Type: object

Metadata collection definition.

Show Source

isEnabled(optional): string

Collection enable (1) or disable (0) status.
isInherited(optional): string

Collection inherited (1) or directly assigned (0) status.
items(optional): array items

List of field definitions.
type(optional): string

Item type collection.

{
    "description":"Metadata collection definition.",
    "type":"object",
    "properties":{
        "type":{
            "type":"string",
            "description":"Item type <code>collection</code>."
        },
        "isEnabled":{
            "type":"string",
            "description":"Collection enable (<code>1</code>) or disable (<code>0</code>) status."
        },
        "isInherited":{
            "type":"string",
            "description":"Collection inherited (<code>1</code>) or directly assigned (<code>0</code>) status."
        },
        "items":{
            "type":"array",
            "description":"List of field definitions.",
            "items":{
                "$ref":"#/definitions/CollectionFieldDefinition"
            }
        }
    }
}

Nested Schema : items

Type: array

List of field definitions.

Show Source

Array of: object CollectionFieldDefinition

Metadata fields definition.

{
    "type":"array",
    "description":"List of field definitions.",
    "items":{
        "$ref":"#/definitions/CollectionFieldDefinition"
    }
}

Nested Schema : CollectionFieldDefinition

Type: object

Metadata fields definition.

Show Source

fieldDescription(optional): string

Field description.
fieldName(optional): string

Field name.
fieldType(optional): string

Field type.
isEnabled(optional): string

Field enable (1) or disable (0) status.
type(optional): string

Item type field.

{
    "description":"Metadata fields definition.",
    "type":"object",
    "properties":{
        "type":{
            "type":"string",
            "description":"Item type <code>field</code>."
        },
        "fieldName":{
            "type":"string",
            "description":"Field name."
        },
        "fieldDescription":{
            "type":"string",
            "description":"Field description."
        },
        "fieldType":{
            "type":"string",
            "description":"Field type."
        },
        "isEnabled":{
            "type":"string",
            "description":"Field enable (1) or disable (0) status."
        }
    }
}

Example Response (application/json)

{
    "idList":"D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "type":"file",
    "errorCode":"0",
    "metadataFields":{
        "CollectionA":{
            "isEnabled":1,
            "isInherited":1,
            "type":"collection",
            "items":[
                {
                    "type":"field",
                    "fieldName":"A1",
                    "fieldType":"string",
                    "isEnabled":1
                },
                {
                    "type":"field",
                    "fieldName":"A2",
                    "fieldType":"string",
                    "isEnabled":0
                }
            ]
        },
        "CollectionB":{
            "isEnabled":1,
            "isInherited":0,
            "type":"collection",
            "items":[
                {
                    "type":"field",
                    "fieldName":"B1",
                    "fieldType":"string",
                    "isEnabled":0
                },
                {
                    "type":"field",
                    "fieldName":"B2",
                    "fieldType":"string",
                    "isEnabled":1
                }
            ]
        }
    }
}

400 Response

Request parameters are not formatted correctly.

404 Response

File ID is not found.

Examples

The following example returns the metadata collection fields associated with the specified file. In this example, both the file and the parent folder have metadata collections associated with them. The response lists the folder collection (CollectionA) followed by the file collection (CollectionB). For each metadata collection, the response returns the definitions of all fields. Also, the value of the status field, isEnabled, shows whether the collection or field is enabled (1) or disabled (0). The field isInherited shows that CollectionA is inherited (1) from the parent folder, and the field also shows that CollectionB is not inherited (0) because it was directly assigned to this file.

GET .../files/D006C2CDD62654ABDCE0B8104EE870070A1AA68C3354/metadataFields

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0",
    "idList": "D006C2CDD62654ABDCE0B8104EE870070A1AA68C3354",
    "metadataFields": {
        "CollectionA": {
            "isEnabled": "1",
            "isInherited": "1",
            "type": "collection",
            "items": [
                {
                    "type": "field",
                    "fieldName": "A1",
                    "fieldType": "string",
                    "isEnabled": "1"
                },
                {
                    "type": "field",
                    "fieldName": "A2",
                    "fieldType": "string",
                    "isEnabled": "0"
                }
            ]
        },
        "CollectionB": {
            "isEnabled": "1",
            "isInherited": "0",
            "type": "collection",
            "items": [
                {
                    "type": "field",
                    "fieldName": "B1",
                    "fieldType": "string",
                    "isEnabled": "0"
                },
                {
                    "type": "field",
                    "fieldName": "B2",
                    "fieldType": "string",
                    "isEnabled": "1"
                }
            ]
        }
    },
    "type": "file"
}

Example 2

The following example returns the metadata collection fields associated with the specified file. In this example, both the file and the parent folder have metadata collections associated with them. The response lists the folder collection (CollectionA) followed by the file collection (CollectionB) and a personal collection (Personal.CollectionA) created by this user and assigned to the folder as well. For each metadata collection, the response returns the definition of all fields. Also, the value of the status field, isEnabled, shows whether the collection or field is enabled (1) or disabled (0). The field isInherited shows that CollectionA and Personal.CollectionA are inherited (1) from the parent folder, and the field also shows that CollectionB is not inherited (0) because it was directly assigned to this file.

GET .../files/D006C2CDD62654ABDCE0B8104EE870070A1AA68C3354/metadataFields

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0",
    "idList": "D006C2CDD62654ABDCE0B8104EE870070A1AA68C3354",
    "metadataFields": {
        "CollectionA": {
            "isEnabled": "1",
            "isInherited": "1",
            "type": "collection",
            "items": [
                {
                    "type": "field",
                    "fieldName": "A1",
                    "fieldType": "string",
                    "isEnabled": "1"
                },
                {
                    "type": "field",
                    "fieldName": "A2",
                    "fieldType": "string",
                    "isEnabled": "0"
                }
            ]
        },
        "CollectionB": {
            "isEnabled": "1",
            "isInherited": "0",
            "type": "collection",
            "items": [
                {
                    "type": "field",
                    "fieldName": "B1",
                    "fieldType": "string",
                    "isEnabled": "0"
                },
                {
                    "type": "field",
                    "fieldName": "B2",
                    "fieldType": "string",
                    "isEnabled": "1"
                }
            ]
        },
        "Personal.CollectionA": {
            "isEnabled": "1",
            "isInherited": "1",
            "type": "collection",
            "items": [
                {
                    "type": "field",
                    "fieldName": "A1",
                    "fieldType": "string",
                    "isEnabled": "1"
                },
                {
                    "type": "field",
                    "fieldName": "A2",
                    "fieldType": "string",
                    "isEnabled": "0"
                }
            ]
        }
    },
    "type": "file"
}

Example 3

The following example returns the metadata collection fields associated with the specified file. The example uses an applink ID because this file is under a folder structure not owned by or shared with the current user. The applink ID and access token are submitted in the request header.

GET .../files/DED694950C14AFF280419F9AB5D17B95F47087F4E518/metadataFields

Request Header

appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg==
accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "errorCode": "0",
    "idList": "DED694950C14AFF280419F9AB5D17B95F47087F4E518",
    "metadataFields": {
        "ApplinkCollection": {
            "isEnabled": "1",
            "isInherited": "1",
            "type": "collection",
            "items": [
                {
                    "type": "field",
                    "fieldName": "appField1",
                    "fieldType": "string",
                    "isEnabled": "1"
                },
                {
                    "type": "field",
                    "fieldName": "appField2",
                    "fieldType": "string",
                    "isEnabled": "1"
                }
            ]
        }
    },
    "type": "file"
}