Squarebox

REST Admin API

Server 7 introduces a new Administration REST API that gives access to all the configuration data held by CatDV Server. Specifically the Admin API allows access to:

Users

Production Groups Roles and Permissions Field Definitions

Panel Definitions View Definition

Media Stores/Media Paths

These APIs are used to support to new web-based administration interface. API Conventions

The Administration REST API is implemented as an extension to the existing CatDV REST API, and shares its basic structure with the rest of the API. Please see the documentation for the CatDV REST API for information about the basic structure and protocols of the API.

Common Object Definitions

Visibility Rules

The visibility of views, panels and other UI elements is controlled by a set of Visibility Rules stored against each item. Each set of Visibility Rules contains three sets of rules:

· Production Group Rules – relate to a catalog’s Production Group

· User Role Rules – relate to the user’s Role.

· Client Rules – relates to the current client:

· CDV – CatDV Desktop Client

· WC1 – CatDV Web Client

· WC2 – CatDV Web 2

· IOS – CatDV iOS Apps

· TRI – CatDV Tricaster Plug-in

· PRE – CatDV Premiere Pro Plug-in Each set of rules consists of two lists:

· Visible To – item is visible to the groups, roles or clients in this list

· Hidden From – item is hidden from the groups, roles or clients in this list Note: If a ‘visible to’ list is empty then the item is always visible.

Each Visibility Rule object contains the following fields:

Field

Type

Description

visibleToGroups

String[]

List of Production Groups that this item is visible to.

hiddenFromGroups

String[]

List of Production Groups that this item is hidden from.

visibleToRoles

String[]

List of Roles that this item is visible to.

hiddenFromRoles

String[]

List of Roles that this item is hidden from.

visibleToClients

String[]

List of Clients that this item is visible to.

hiddenFromClients

String[]

List of Clients that this item is hidden from.

Endpoint: /users

Represents the collection of all the users defined on the server:

Object Definitions

User Object

Represents a user who can log in to the CatDV system. Each User object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of user

name

String

User’s name

notes

String

Additional notes about the user

roleID

Integer

ID of this User’s Role

role

String

Name of this User’s Role

Operations

GET /users

Returns an array of all the users defined on the server.

GET /users/<user_id>

Returns the user with the specified id.

POST /users

Add a new user to the system. POST data contains JSON User object. Returns the ID of the newly created User.

PUT /users/<user_id>

Update the User specified by <user_id> with the values in the JSON User object passed in the PUT data. Only fields present in the passed in JSON User object will be updated.

DELETE /users/<user_id>

Delete the User specified by <user_id>. Any items currently owned by the user will pass to the anonymous user.

Endpoint: /groups

Represents the collection of all the Production Groups defined on the server:

Object Definitions

Production Group Object

Represents a Production Group in to the CatDV system. Each Production Group object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of Production Group

name

String

Name of this Production Group

notes

String

Additional notes about the group

defaultPermissions

String[]

List of permissions that new members of this group get.

Operations

GET /groups

Returns an array of all the role defined on the server.

GET /groups/<group_id>

Returns the Production Group with the specified <group_id>.

POST /groups

Create a new Production Group based on the JSON Production Group object passed in the POST data. Returns the ID of the newly created Production Group.

PUT /groups/<group_id>

Update the Production Group specified by <group_id> with the values in the JSON Production Group object passed in the PUT data. Only fields present in the passed in JSON Production Group object will be updated.

PUT /groups/<groupID>/roles

Update the Role Permissions for this Production Group. PUT data contains an array of Role objects, each with two fields set – the Role’s ID and the Role’s Permissions with respect this Production Group. Roles not present in the list are assumed to have no Permissions with respect to this Production Group and will have any existing permissions removed.

DELETE /groups/<group_id>

Delete the Production Group specified by <group_id>.

Endpoint: /roles

Represents the collection of all the Roles defined on the server:

Object Definitions

Role Object

Represents a Role, which can be thought of as a permission template that a number of users can share. Each Role object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of Role

name

String

Name of this Role

notes

String

Additional notes about the Role

List of permissions for this Role with respect to a particular Production Group. This field is only used in contexts where the Production Group is specified, generally as an additional parameter to the REST API call.

Available Role Permissions are:

readOthersCatalogs – can read catalogs belonging to others.

createCatalogs – can create catalogs.

editCatalogs – can edit clips and catalog details of catalogs owned by them.

editOthersCatalogs – can edit clips and catalog details of catalogs owned by others.

Operations

GET /roles

Returns an array of all the Role defined on the server.

GET /roles/<role_id>

Returns the production role with the specified <role_id>.

GET /roles/<roleID>/permissions?groupID=<groupID>

Returns the set of Role Permissions (as a String[]) that apply to the specified Role with respect to the specified Production Group.

POST /roles

Create a new Role based on the JSON Role object passed in the POST data. Returns the ID of the newly created Role.

PUT /roles/<role_id>

Update the Role specified by <role_id> with the values in the JSON Role object passed in the PUT data. Only fields present in the passed in JSON Role object will be updated.

DELETE /roles/<role_id>

Delete the Role specified by <role_id>.

Endpoint: /fieldgroups

Represents the collection of all the Field Groups defined on the server. All user-defined fields belong to exactly one Field Group. The Field Group defines the type of the object (clip, catalog etc.) that the field definitions it contains pertain to.

Object Definitions

Field Group Object

Field

Type

Description

ID

Integer

Unique ID of this FieldGroup.

name

String

Name of this Field Group.

description

String

Longer description

objectClass

String

Class of object that the fields contain

identifierPrefix

String

Optional prefix that will be applied (by the admin UI) to the identifiers of any fields created in this group.

isBuiltIn

Boolean

True for built-in field groups e.g. the ‘All Fields’ field group. These built-in groups are generated on the fly and cannot be edited

originType

String

High-level categorization of the origin of this field group. Values are:

user-defined – created directly by a user plugin – created by a server plugin (e.g. archive status fields) file-metadata – created by CatDV to store filed metadata (e.g. EXIF fields) fieldset – migrated from a pre-server 7 field set

originInfo

String

Further details about the origin of this field group – e.g. the name of the legacy field set or the plugin that created the fields.

visibility

VisibilityRules

Rules to determine who can see these fields (only applies to the fields offered to user when constructing a query – does not control whether fields on a panel are visible or not – that is controlled by panel-level visibility rules)

Operations

GET /fieldgroups

Returns an array of all the field groups on the server.

GET /fieldgroups/<field_group_id>

Returns the field group with the specified <field_group_id>.

POST /fieldgroups

Create a new field group based on the JSON FieldGroup object passed in the POST data. Returns the ID of the newly created FieldGroup.

PUT /fieldgroups/<field_group_id>

Update the FieldGroup specified by <field_group_id> with the values in the JSON FieldGroup object passed in the PUT data. Only fields present in the supplied JSON FieldGroup object will be updated.

DELETE /fieldgroups/<field_group_id>

Delete the FieldGroup specified by <field_group_id>.

Endpoint: /fields

Represents the collection of all the Field Definitions defined on the server:

Object Definitions

Field Definition Object

Represents a, usually user-defined, field on a particular type of CatDV object (e.g. Clip, SourceMedia, Marker etc.) Each Field Definition object contains the following fields:

Field

Type

Description

ID

String

Unique ID of this FieldDefinition. For built-in fields this is the familiar CatDV field short code (e.g. NM1, STS etc.). For user-defined

fields it the unique numeric ID of the object.

fieldGroupID

Integer

Unique ID of this FieldGroup that this FieldDefinition belongs to.

memberOf

String

Type of object this field definition belongs to. Possible values are:

· catalog

· clip

· media

· importSource

· marker

· other custom object class identifier

identifier

String

Unique (within the given object type) name (or ‘slug’) for this field definition.

To ensure that the identifier is unique it is generally built up from a domain-specific prefix, such as the field’s group, or the vender reverse domain, followed by a simplified version of the field’s name, with spaces converted to periods and all lowercase.For user- defined fields this value as the ‘name’ of the property in an object’s metadata object, whereas for built-in fields this value is the name of the field in the relevant object. For example the Field Definition for clip.name (NM1), would have memberOf=”clip” and identifier=”name”.

name

String

Descriptive name for the field. Used as the label when the field is displayed in the UI.

description

String

Longer description of the field. Used as the tooltip when the field is displayed in the UI.

fieldType

String

Type of data stored in this field and how the field should be presented to the user. Possible values are:

text – plain text

multiline – multi-line plain text field

date – a date

time – time of day number – a number identifier – arbitrary string hidden – hidden field checkbox – a checkbox

multi-checkbox – a set of checkboxes

radio – set of radio buttons

picklist – single value selected from a drop down list

multi-picklist – multiple values selected from a drop down list

hierarchy – single value selected from a hierarchical list

multi-hierarchy – multiple values selected from a hierarchical list

linked-multi-hierarchy – multiple values selected from a hierarchical list linked to another field

auto-suggest – a value which may be one selected from a list of values

multi-auto-suggest – multiple values which may be ones selected from a list of values

html – a rich formatted HTML field

isBuiltIn

Boolean

True if this Field Definition represents a built-in field.

canQuery

Boolean

True if this field can be used in a clip query.

isSortable

Boolean

True if this field can be used to sort the results of a clip query.

isCalculated

Boolean

(Only present for built-in fields). Hint to tell client that this built-in field

is not directly represented by a field on the relevant object. For example the “IO” field displays

the In timecode and the Out timecode in a single field. The value to display must therefore be calculated by the client.

isEditable

Boolean

True if any user can edit this field (assuming they have the necessary permissions).

isMandatory

Boolean

True if the user must enter a value in this field.

isMultiValue

Boolean

True if multiple values can be stored against this field. This is a calculated field based on the type of the field.

isList

Boolean

True if a list of possible values is associated with this field. This is a calculated field based on the type of the field.

values

String[]

For list fields this field can optionally be populated with all the list values.

Picklist Object

Represents the list of values for fields where the user selects a value from a list (e.g. picklist, hierarchy etc.). Each View Set object contains the following fields (Note that not all client support all options):

Field

Boolean

Description

isExtensible

Boolean

True is user is allowed to enter values that are not in the list.

isKeptSorted

Boolean

Values are kept sorted in alphabetical order.

savesValues

Boolean

Non-list values get added to the list.

isLocked

Boolean

Only administrators can add values.

values

String[]

The list of values.

Operations

GET /fields[?include=<include_flags>][&filter=<filter>]...

Returns a PartialResultSet of Field Definitions that conform to the passed in parameters:

Parameter

Function

include

Determines which Field Definitions to include in the results and also whether to return additional related data within each Field Definition. Supported values are:

builtin – include built-in fields

catalog – include user-defined catalog fields

catalog.builtin – include built-in catalog fields

clip – include user-defined clip fields

media – include user-defined source media metadata fields

source– include user-defined import source metadata fields

marker – include user-defined marker fields

user – include user-defined user fields

cliplist – include user-defined clip list fields

picklists – for picklist fields include the associated picklist

values – include picklist values for picklist fields

fieldGroup – include the containing field group.

onlySimpleSearchable – only include fields that can be searched

onlyQueryable – only include fields that can be queried

onlyEditable – only include that can be edited

onlyFilterable – only include that can be included in a filter

onlyVisible – only include that are visible to the current user based on field group visibility

onlySortable – only include that can be used to sort the result set.

filter

Only return FieldDefinitions whose name contains the specified string

skip/take

Controls which portion of the result set to return. See PartialResultSet

groupID

For built-in fields, use the specified group to determine the correct set of Picklist values if applicable.

onlyQueryableFields

Only return FieldDefinitions for fields that can be used in Clip Query filter expressions

GET /fields/<field_id>

Returns the Field Definition with the specified <field_id>, where <field_id> can be either the numeric ID of a user-defined custom field, or the short string ID of a built-in field (e.g. NM1, STS etc.).

GET /fields/<field_id>/list[?groupID=<group_id>][&include=values]

Returns the Picklist object associated with the FieldDefinition specified by <field_id>, where <field_id> can be either the numeric ID of a user-defined custom field, or the short string ID of a built-in field (e.g. NM1, STS etc.). For built-in fields the groupID parameter must be provided to identify the Production Group that the Picklist definition should be taken from.

If the optional include=values parameter is included then the actual picklist values are included with with the picklist.

GET /fields/<field_id>/list/values[?groupID=<group_id>]

Returns the Picklist values associated with the FieldDefinition specified by <field_id>, where <field_id> can be either the numeric ID of a user-defined custom field, or the short string ID of a built-in field (e.g. NM1, STS etc.). For built-in fields the groupID parameter must be provided to identify the Production Group that the values should be taken from.

GET /fields/<field_id>/values

Returns a complete list of all the unique values held in the database for the specified field. For large databases this can be an expensive operation, since every clip needs to be considered.

GET /fields/types

Returns all the available user-defined field types as an array of ID/Name pairs.

POST /fields

Create a new Field Definition based on the JSON Field Definition object passed in the POST data. Returns the ID of the newly created Field Definition.

PUT /fields/<field_id>

Update the Field Definition specified by <field_id> with the values in the JSON FieldDefinition object passed in the PUT data. Only properties present in the passed in JSON FieldDefinition object will be updated.

PUT /fields/<field_id>/list[?groupID=<group_id>]

Update the Picklist associated with the Field Definition specified by <field_id> with the values in the JSON Picklist object passed in the PUT data. The values of <field_id> can be either the numeric ID of a user-defined custom field, or the short string ID of a built-in field (e.g. NM1, STS etc.). For built-in fields the groupID parameter must be provided to identify the Production Group that the Picklist belongs to.

DELETE /fields/<field_id>

Delete the Field Definition specified by <field_id>.

Endpoint: /viewsets

Represents the collection of all the viewsets defined on the server:

Object Definitions

View Set Object

Represents a set of views (ViewDefinitions) where each view may be a list a grid or filmstrip. View Sets exists to make it easier to manage which views should appear under what situations. For example one might wish to define one View Set that defines the views that appear for a particular Production Group, or one a particular type of client (e.g. Web or iOS). Each View Set object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of this ViewSet.

name

String

Name of this ViewSet.

description

String

Longer description of this ViewSet.

visibility

VisibilityRules

Set of rule that determine when this ViewSet should be displayed.

order

Integer

Used to specify the position that this ViewSet will appear in lists of ViewSets.

views

ViewDefinition[]

List of the ViewDefinitions that make up this View Set.

Operations

GET /viewsets

Returns an array of all the viewsets defined on the server.

GET /viewsets/<viewset_id>

Returns the ViewSet with the specified id.

POST /viewsets

Add a new ViewSet to the system. POST data contains JSON ViewSet object. Returns the ID of the newly created ViewSet.

PUT /viewsets/<viewset_id>

Update the ViewSet specified by <viewset_id> with the values in the JSON ViewSet object passed in the PUT data. Only fields present in the passed in JSON ViewSet object will be updated.

DELETE /viewsets/<viewset_id>

Delete the ViewSet specified by <viewset_id>.

Endpoint: /views

Represents the collection of all the views defined on the server:

Object Definitions

View Definition Object

Represents the fields to be displayed with each item in a list, grid or filmstrip list of clips.

Note that currently only the desktop CatDV client supports all the available view options. The Web Client and Web 2 interface currently only support customisation of Normal, Concise and Full views.

Each View Definition object contains the following fields:

Field

Type

Description

ID

Integer

Unique ID of this ViewDefinition.

name

String

Name of this ViewDefinition.

description

String

Longer description of this ViewDefinition.

type

String

What type of panel or view does this ViewDefinition define. Possible values:

builtin – a built-in CatDV view

list – a tabular list view

grid – a grid view

list – a filmstrip view

options

JSONObject

Set of options that can be applied to the various view types. Possible values are:

list

spacing – normal or wide

grid

size – small, medium, large or huge

text – none, right or below filmstrip

size – small, medium or large allThumbnails -true or false poster -true or false

visibility

VisibilityRules

Set of rule that determine when this ViewDefinition should be displayed.

order

Integer

Used to specify the position that this ViewSet will appear in lists of ViewSets.

fields

ViewField[]

List of the ViewFields that make up this View Definition.

View Field Object

Represents an individual fiels within the view. Each View Field object contains the following fields:

Field

Type

Description

ID

Integer

Unique ID of this ViewSet.

viewDefID

Integer

ID of the containing ViewDefinition.

fieldDefID

Integer

ID of the FieldDefinition of the field.

fieldDefinition

FieldDefinition

Optionally a copy of the FieldDefinition object for this field.

Operations

GET /views[?include=<include_options>][&groupID=<group_id>]

Returns an array of the views defined on the server based on the supplied parameters.

Parameter

Function

include

Determines which views to include in the results and also whether to return additional related data within each view. Supported values are:

builtin – include built-in Views

fields – include the fields defined in each View

fieldDefs – include the associated FieldDefinition for each of the View’s fields.

values – include Picklist values for Picklist fields

groupID

For built-in fields, use the specified group to determine the correct set of Picklist values if applicable.

GET /views/<view_id>

Returns the user with the specified id.

GET /views/<view_id>/fields

Returns the ViewFields defined for the the specified view.

POST /views

Add a new user to the system. POST data contains JSON View object. Returns the ID of the newly created View.

PUT /views/<view_id>

Update the View specified by <view_id> with the values in the JSON View object passed in the PUT data. Only fields present in the passed in JSON View object will be updated.

PUT /views/<view_id>/fields

Update the fields associated with the specified View using with the array of JSON ViewField objects passed in the PUT data.

DELETE /views/<view_id>

Delete the View specified by <view_id>.

Endpoint: /panelsets

Represents the collection of all the PanelSets defined on the server:

Object Definitions

Panel Set Object

Represents a set of panels (PanelDefinitions). Panel Sets exists to make it easier to manage which panels should appear under what situations. For example one might wish to define one Panel Set that defines the panels that appear for a particular Production Group, or one a particular type of client (e.g. Web or iOS). Each Panel Set object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of this PanelSet.

name

String

Name of this PanelSet.

description

String

Longer description of this PanelSet.

visibility

VisibilityRules

Set of rule that determine when this PanelSet should be displayed.

order

Integer

Used to specify the position that this PanelSet will appear in lists of PanelSets.

panels

PanelDefinition[]

List of the PanelDefinitions that make up this Panel Set.

Operations

GET /panelsets

Returns an array of all the PanelSets defined on the server.

GET /panelsets/<panelset_id>

Returns the PanelSet with the specified id.

POST /panelset

Add a new PanelSet to the system. POST data contains JSON PanelSet object. Returns the ID of the newly created PanelSet.

PUT /panelsets/<panelset_id>

Update the PanelSet specified by <panelset_id> with the values in the JSON PanelSet object passed in the PUT data. Only fields present in the passed in JSON PanelSet object will be updated.

DELETE /PanelSets/<panelset_id>

Delete the PanelSet specified by <panelset_id>.

Endpoint: /panels

Represents the collection of all the panels defined on the server:

Object Definitions

Panel Definition Object

Represents the fields to be displayed on the panel (tab). Each Panel Definition object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of this PanelDefinition.

name

String

Name of this PanelDefinition.

description

String

Longer description of this PanelDefinition.

type

String

What type of panel or panel does this PanelDefinition define. Possible values:

builtin – a built-in CatDV panel

normal– a normal CatDV metadata panel

html– a read-only formatted HTML panel

visibility

VisibilityRules

Set of rule that determine when this PanelDefinition should be displayed.

order

Integer

Used to specify the position that this PanelSet will appear in lists of PanelSets.

Panel Field Object

Represents an individual fiels within the panel. Each Panel Field object contains the following fields:

Field

Type

Description

ID

Integer

Unique ID of this PanelSet.

panelDefID

Integer

ID of the containing panel.

fieldDefID

Integer

ID of the FieldDefinition of the field.

readOnly

Boolean

True if user is not allowed to edit this field.

hideIfBlank

Boolean

True if field should be hidden if it is blank.

spanTwoColumns

Boolean

True if field show span two columns.

multiline

Boolean

True if field should be displayed over multiple lines

fieldDefinition

FieldDefinition

Optionally a copy of the FieldDefinition object for this field.

Operations

GET /panels[?include=<include_options>][&groupID=<group_id>]

Returns an array of the panels defined on the server based on the supplied parameters.

Parameter

Function

include

Determines which panels to include in the results and also whether to return additional related data within each panel. Supported values are:

builtin – include built-in Panels

fields – include the fields defined in each Panel

fieldDefs – include the associated FieldDefinition for each of the Panel’s fields.

values – include Picklist values for Picklist fields

groupID

For built-in fields, use the specified group to determine the correct set of Picklist values if applicable.

GET /panels/<panel_id>

Returns the user with the specified id.

GET /panels/<panel_id>/fields

Returns the PanelFields defined for te the specified panel.

POST /panels

Add a new user to the system. POST data contains JSON Panel object. Returns the ID of the newly created Panel.

PUT /panels/<panel_id>

Update the Panel specified by <panel_id> with the values in the JSON Panel object passed in the PUT data. Only fields present in the passed in JSON Panel object will be updated.

PUT /panels/<panel_id>/fields

Update the fields associated with the specified Panel using with the array of JSON PanelField objects passed in the PUT data.

DELETE /panels/<panel_id>

Delete the Panel specified by <panel_id>.

Endpoint: /formsets

Represents the collection of all the FormSets defined on the server:

Object Definitions

Form Set Object

Represents a set of forms (FormDefinitions). Form Sets exists to make it easier to manage which forms should appear under what situations. For example one might wish to define one Form Set that defines the forms that appear for a particular Production Group, or one a particular type of client (e.g. Web or iOS). Each Form Set object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of this FormSet.

name

String

Name of this FormSet.

description

String

Longer description of this FormSet.

visibility

VisibilityRules

Set of rule that determine when this FormSet should be displayed.

order

Integer

Used to specify the position that this FormSet will appear in lists of FormSets.

forms

FormDefinition[]

List of the FormDefinitions that make up this Form Set.

Operations

GET /formsets

Returns an array of all the FormSets defined on the server.

GET /formsets/<formset_id>

Returns the FormSet with the specified id.

POST /formset

Add a new FormSet to the system. POST data contains JSON FormSet object. Returns the ID of the newly created FormSet.

PUT /formsets/<formset_id>

Update the FormSet specified by <formset_id> with the values in the JSON FormSet object passed in the PUT data. Only fields present in the passed in JSON FormSet object will be updated.

DELETE /FormSets/<formset_id>

Delete the FormSet specified by <formset_id>.

Endpoint: /forms

Represents the collection of all the forms defined on the server:

Object Definitions

Form Definition Object

Represents the fields to be displayed on the form (tab). Each Form Definition object contains the following fields

Field

Type

Description

ID

Integer

Unique ID of this FormDefinition.

name

String

Name of this FormDefinition.

description

String

Longer description of this FormDefinition.

type

String

What type of form or form does this FormDefinition define. Possible values:

search – a search form navsearch – special search form that appears in nav-tree upload – form to enter metadata to be included with file upload subclip – for to enter metadata for new subclip filter – filter definition

visibility

VisibilityRules

Set of rule that determine when this FormDefinition should be displayed.

order

Integer

Used to specify the position that this FormSet will appear in lists of FormSets.

Form Field Object

Represents an individual fiels within the form. Each Form Field object contains the following fields:

Field

Type

Description

ID

Integer

Unique ID of this FormSet.

formDefID

Integer

ID of the containing form.

fieldDefID

Integer

ID of the FieldDefinition of the field.

spanTwoColumns

Boolean

True if field should two layout columns (Upload Forms only).

multiline

Boolean

True if field should be displayed over multiple lines (Upload Forms only).

mandatory

Boolean

True if field must be filled in before form can be submitted (Upload Forms only)..

Operations

GET /forms[?include=<include_options>][&groupID=<group_id>]

Returns an array of the forms defined on the server based on the supplied parameters.

Parameter

Function

include

Determines which forms to include in the results and also whether to return additional related data within each form. Supported values are:

builtin – include built-in Forms fields – include the fields defined in each Form fieldDefs – include the associated FieldDefinition for each of the Form’s fields. values – include Picklist values for Picklist fields

groupID

For built-in fields, use the specified group to determine the correct set of Picklist values if applicable.

GET /forms/<form_id>

Returns the user with the specified id.

GET /forms/<form_id>/fields

Returns the FormFields defined for te the specified form.

POST /forms

Add a new user to the system. POST data contains JSON Form object. Returns the ID of the newly created Form.

PUT /forms/<form_id>

Update the Form specified by <form_id> with the values in the JSON Form object passed in the PUT data. Only fields present in the passed in JSON Form object will be updated.

PUT /forms/<form_id>/fields

Update the fields associated with the specified Form using with the array of JSON FormField objects passed in the PUT data.

DELETE /forms/<form_id>

Delete the Form specified by <form_id>.

Endpoint: /mediastores

Represents the collection of all the mediastores defined on the server:

Object Definitions

Media Store Object

Represents a logical storage volume where media is held. Each store contains one or more Media Paths that refer to physical locations on shared storage. Each Media Store object contains the following fields:

Field

Boolean

Description

ID

Integer

Unique ID of this Media Store.

name

String

Name of this Media Store.

paths

MediaPath[]

List of Media Paths contained by this Media Store.

Media Store Path Type Object

Represents the type of a Media Store Path. For example, types would typically include “Original Hires Media”, “Web Video Proxy” and “Filmstrip”. Each Media Store Path has a mediaStoreTypeID the specifies the type of that path:

Field

Boolean

Description

ID

Integer

Unique ID of this Media Path Type.

name

String

Name of this Media Path Type.

mediaType

String

Type of media this media path type refers to. Valid values are:

· hires

· proxy

· filmstrip

· audio

· subtitle

mediaSubType

String

(Optional) Specifies a user-defined sub-type for the media. For example this field could be used to define multiple types of proxy file, with different resolutions or compression. If this field is specified then this Media Path Type will become available as an option in the Download function.

target

String

(Optional) Specifies the context at which this path type is targetted. Valid values are:

· client - Path is valid for the Desktop client’s filesystem.

· web - Path refers to media valid for the playback on in a browser. The path itself must be valid for the CatDV Server’s filesystem

· worker - Path is valid for the Worker node’s filesystem.

· server - Path is valid for the CatDV Server’s filesystem.

· adobe – Path is valid for the Adobe CC client’s filesystem and refers to media suitable for playback in the Adobe CC application. (Used by the Adobe Panel)

· fcpx - Path is valid for the Final Cut Pro client’s filesystem and refers to media suitable for playback in Final Cut Pro. (Used by the Final Cut Pro Workflow Extension)

· aspera – Path is a URL in the following format ‘aspera://<aspera_target>/<path>’ that specifies a location on the specified Aspera server.

· archiware – Path is valid on the Archiware Server. (Used by the Archiware Archiving Server Plugin)

extensions

String

(Optional) List of file extensions (e.g. .mp4,.mov) that the server should use in place of the original extension when looking up proxy media, or (required) for cases where the path in not a valid server path, so the server cannot perform file existence checks itself (for example for Adobe Panel proxy paths)

Media Store Path Object

Field

Boolean

Description

ID

Integer

Unique ID of this Media Path.

mediaStoreID

Integer

ID of containing Media Store.

pathTypeID

Integer

ID of the Media Path Type entry that defines the type of this Media Path

hires – original hi-resolution media

proxy – lower-resolution proxy media

proxy.web – lower-resolution proxy encoded for web use

path

String

Path of this location.

pathOrder

Number

Sort of paths – defines priority where multiple candidate paths exist.

Represents a location on shared storage where a particular type of media is held (e.g. hi-res, proxy etc.) as seen by a particular type of client (e.g.

Windows, Mac OS etc.). For example, if a location

on shared storage was mounted on Mac clients as /Volumes/SAN/Media, but on Windows machines as \\san\media, then you would store two paths, one targeting client.win and one targeting client.mac.

Each Media Path object contains the following fields:

Operations

GET /mediastores

Returns an array of all the Media Stores defined on the server.

GET /mediastores/pathtypes

Returns an array of all the Media Store Path Types defined on the server.

GET /mediastores/downloadtypes

Returns an array of all the Media Store Path Types defined on the server that have a ‘sub-types’ set. These path types are used to present the set of file type options in the download function.

GET /mediastores/<mediastore_id>

Returns the Media Store with the specified id.

POST /mediastores

Add a new Media Store to the system. POST data contains JSON Media Store object. Returns the newly created Media Store.

POST /mediastores/pathtypes

Add a new Media Store Path Type to the system. POST data contains JSON Media Store Type object. Returns the newly created Media Store Path Type.

POST/mediastores/<mediastore_id>/paths

Add a new Media Store Path to the Media Store specified by <mediastore_id>.

PUT /mediastores/<mediastore_id>

Update the Media Store specified by <mediastore_id> with the values in the JSON MediaStore object passed in the PUT data. Only fields present in the passed in JSON Media Store object will be updated.

PUT /mediastores/pathtypes/<mediastorepathtype_id>

Update the Media Store Path Type object specified by < mediastorepathtype _id> with the values in the JSON Media Store Store Path Type object passed in the PUT data. Only fields present in the passed in JSON Media Store Path Type object will be updated.

PUT /mediastores/<mediastore_id>/paths/<mediapath_id>

Update the Media Store Path specified by <mediapath_id> within the Media Store Path specified by <mediastore_id> with the values in the JSON Media Store Path object passed in the PUT data. Only fields present in the passed in JSON Media Store Path object will be updated.

DELETE /mediastores/<mediastore_id>

Delete the Media Store specified by <mediastore_id>.

DELETE /mediastores/pathtypes/<mediastorepathtype_id>

Delete the Media Store Path Type object specified by < mediastorepathtype _id>.

DELETE /mediastores/<mediastore_id>/paths/<mediapath_id>

Delete the Media Store Path specified by <mediastore_id> and /<mediapath_id>.