• Register

Metadata API

The Metadata API allows you to define custom metadata fields and then use those fields to set values on files, file versions, and folders. Metadata fields (keys) are grouped together in namespaces.

Namespaces can be either private, protected, or public. Private namespaces are only visible to the application that created them (i.e. only when accessing with the same Public API key). Protected namespaces are visible to any applicaiton and the Web UI, but can only be modified/deleted by the application that created them. Public namespaces are visible to any application and are also visible within the Web UI. They can also be modified/deleted by any applicaiton or via the Web UI

Common HTTP Headers

Header Description Value
Content-Type Specifies the format of the request body application/json
Authorization Requires the OAuth token you obtained through the OAuth flow Bearer {OAuth token}
Error Description
200 Successful operation
403 User is not authorized
404 Item not found

Get All Namespaces

This endpoint is used to list all custom metadata namespaces in the domain.

GET/pubapi/v1/properties/namespace

Create Namespace

This endpoint is used to create a namespace of custom metadata fields for a domain.

POST/pubapi/v1/properties/namespace

Request Parameters

Parameter Description Required Possible Values
name What you call the namespace Yes string
displayName The name to identify the namespace in the UI No string
scope Who can see and modify the namespace Yes public, protected, private
keys The custom metadata key(s) you are creating Yes JSON object (see create metadata key endpoint for fields)
type Specifies the data type for a key. Yes integer, string, decimal, date (Unix epoch time), enum
priority Specifies the priority (order) for the keys. The keys will be displayed in accordance with their priorities in descending order (keys with higher priority will be displayed first).

Note: if priorities of two (or more) keys are the same, the keys will be displayed one after another in an arbitrary order.		 No integer value 0, 1, 2, 3, ...
data For a key of enum type, specifies the enumerated values. Only required for enum E.g. ["red", "green", "blue"]
helpText Instructional text that is displayed when a user is adding/editing a property to give context as to the property's purpose No string

Sample Request Body

{
  "name": "namespace1",
  "scope": "public",
  "displayName": "my first namespace",
  "keys": {
    "int-key": {
      "type": "integer",
      "priority": 5,
      "displayName": "my key"
    },
    "decimal-key": {
      "type": "decimal",
      "priority": 3
    },
    "string-key": {
      "type": "string",
      "priority": 2
    },
    "enum-key": {
      "type": "enum",
      "data": ["val1", "val2"]
    },
    "date-key": {
      "type": "date"
    }    
  }
}

Update Namespace Attributes

This endpoint is used to update the name of a custom metadata for a domain.

PATCH/pubapi/v1/properties/namespace/{namespace name}

Request Parameters

Parameter Description Required Possible Values
displayName The name to identify the namespace in the UI No string
priorities Specifies priorities (the order) for the keys. The keys will be displayed in accordance with their priorities in descending order (keys with higher priority will be displayed first).

Note: if priorities of two (or more) keys are the same, the keys will be displayed one after another in an arbitrary order.		 No Keys and their priorities - integer numbers 0,1,2, ...

Sample Request Body

{
  "displayName": "a namespace with a new name",
  "priorities": { "first_name": 5, "last_name": 3, "role": 1}

}

Update Namespace Keys

This endpoint is used to update the key definitions of a namespace of custom metadata fields for a domain.

PATCH/pubapi/v1/properties/namespace/{namespace name}/keys/{key name}

Request Parameters

Parameter Description Required Possible Values
displayName Specifies the name displayed for the key No string
type Specifies the data type for a key. Can only allow a change to a broader type:
  • decimal -> string
  • integer -> string, decimal
  • date -> string, decimal, integer
  • enum -> string (in this case the 'data' parameter will be automatically set to null)
 No integer, string, decimal, date, enum
priority Specifies the priority (order) for the key. In general, keys will be displayed in accordance with their priorities in descending order (keys with higher priority will be displayed first).

Note: if priorities of two (or more) keys are the same, the keys will be displayed one after another in an arbitrary order.		 No integer value 0, 1, 2, 3, ...
data For a key of enum type, specifies the enumerated values. Only new values are allowed Only required for enum E.g. ["red", "green", "blue"]
helpText Instructional text that is displayed when a user is adding/editing a property to give context as to the property's purpose No string

Sample Request Body

{
  "displayName": "My new display name",
  "helpText": "Use this key",
  "data": ["red", "green", "blue", "new color"],
  "priority": 21,
  "type": "enum"
}

Get Namespace

This endpoint is used to list all custom metadata keys that have been created in a given namespace.

GET/pubapi/v1/properties/namespace/{namespace name}

Delete Namespace

This endpoint is used to delete a specified namespace.

DELETE/pubapi/v1/properties/namespace/{namespace name}

When the namespace is in use, 403 HTTP error ("Cannot delete a namespace because it is used") will be returned. To delete the namespace anyway, it is necessary to set "X-Egnyte-Force-Delete" HTTP header value to Yes.

Create Metadata Key

This endpoint is used to add a metadata key to an existing namespace.

POST/pubapi/v1/properties/namespace/{namespace name}/keys

Request Parameters

Parameter Description Required Possible Values
key The name of the key you are creating Yes string
type Specifies the data type for a key. Yes integer, string, decimal, date, enum
displayName The name to identify the field in the UI. No string
priority Specifies priority for the key (keys with the higher priority will be displayed first. No 0,1,2,...
helpText A tooltip description for the metadata field. No string
data For a key of enum type, specifies the enumerated values. Only required for enum E.g. ["red", "green", "blue"]

Sample Request Body

{
  "key": "new-enum-key",
  "type": "enum",
  "data": ["red", "green", "blue"],
  "displayName": "My new key for values",
  "priority": 7,
  "helpText": "Use this key to tag files with these values"
}

Delete Metadata Key

This endpoint is used to delete a metadata key from an existing namespace.

DELETE/pubapi/v1/properties/namespace/{namespace name}/keys/{key name}

When the key is in use, 403 HTTP error ("Cannot delete a key because it is used") will be returned. To delete the key anyway, it is necessary to set "X-Egnyte-Force-Delete" HTTP header value to Yes.

Set Values for a Namespace

This endpoint is used to set a metadata values for a given namespace for a file, file version, or folder. This endpoint allows multiple key/value pairs to be set at once. If the key already has a value, the old value will be overwritten by the new value. If the value for a key is set to null, the existing value will be removed. For more information on interacting with files, specific file versions, or folders, please refer to the File System API documentation.

To set a metadata value for a file, use the group ID of the file. To set a metadata value for a specific file version, use the entry ID of the file version. To set a metadata value for a folder, use the folder ID.

PUT/pubapi/v1/fs/ids/file/{group_id or entry_id}/properties/{namespace name}
PUT/pubapi/v1/fs/ids/folder/{folder_id}/properties/{namespace name}

Sample Request Body

{
  "string-key": "abc",
  "int-key": "10",
  "date-key": "1465413843995"
}

Get Values for a Namespace

This endpoint is used to get the metadata values for a given namespace for a file, file version, or folder. For more information on interacting with files, specific file versions, or folders, please refer to the File System API documentation.

GET/pubapi/v1/fs/ids/file/{group_id or entry_id}/properties/{namespace name}
GET/pubapi/v1/fs/ids/folder/{folder_id}/properties/{namespace name}

Sample Respose Body

{
  "results": [
    {
      "workspace": {
        "string-key": "abc",
        "int-key": 10
      }
    }
  ]
}

Search Metadata

This endpoint is used to find items that have a specific metadata field or to find items that have a field that contains a specific value.

POST /pubapi/v1/search

Request Parameters

Parameter Description Required Possible Values
type Which item types should be searched No ALL, FOLDER, FILE
has_key Allows for finding items that have a specific key. If multiple objects are included in the array, any item matching one or more of the conditions will be returned. No An array of objects with keys "namespace" and "key", e.g. [{"namespace": "namespace1", key: "string-key"}]
key_with_value Allows for finding items that contain a specific string within a metadata value for a specified field. Note that this is not an exact match, but rather looks for any string that contains the search term. If multiple objects are included in the array, any item matching one or more of the conditions will be returned. No An array of objects with keys "namespace", "key", and "value", e.g. [{"namespace": "namespace1", key: "string-key", "value": "abc"}]

Sample Request Body

{
  "type": "ALL",
  "key_with_value": [
    {
      "namespace": "namespace1",
      "key": "string-key",
      "value": "abc"
    }
  ]
}

version 48 as of 2 years ago by Vitaly Obernikhin