enterprise_api_lookup_domains.md

Enterprise API Lookup Domains

DF Studio supports Custom Lookup Domains - Enterprise-controlled terms a user picks from when editing a metadata field. The terms available for a field are based the path in DF Studio (path), and/or the value of another metadata field (meta). Terms or Options are associated with Folders and Projects in DF Studio (path) and/or with specific values of fields on the Asset. Path based terms can be edited from within DF Studio (or can be hidden); All terms can be edited from the Enterprise API. The Enterprise API (found at https://yourdomain.dfstudio.com/api/v1/session.js) has several new resources which can be used to manage Lookup Domain values.

Lookup Domain Terms can also optionaly have Labels associated with them. When a label is present it will be shown in the DF Studio interface and used for Search Indexing. The value will be shown in the Enterprise API. Labels are optional and only supported for Dropdowns, Radio, Checkboxes, and Selectors.

This document covers the new resources available in the Enterprise API.

Documentation Conventions

• [SID]: replace with the session id
• [BASE]: yourdomain.dfstudio.com
• [FIELD]: dfstudio.keywords or custom.myCustomField

All URLs will end in js, however xml is supported along with easy to explore html

API

List Domains

List all Lookup Domains defined. Note the property field: Lookup Domains are identified by the field they are associated with. [FIELD] is replaced with the field name for a domain.

GET [BASE]/api/v1/session/[SID]/domains.js

//RESPONSE: 
{
  "results": [
    {
      "field": "custom.subcategory",
      "lookupRules": [ "meta_custom_category" ],
      "addTo": "meta_custom_category",
      "rest.resourceName": "domain"
    }
  ]
}

List Lookup Keys

List the lookup keys for this field, these values replaced [KEY] in the next URL.

GET [BASE]/api/v1/session/[SID]/domain/[FIELD]/meta.js

//RESPONSE:
[
  "fruit",
  "vehicles",
  "sizes"
]

List Lookup Terms

List all terms for a Lookup Domain and given lookup key. The field isAdded indicates if a user in DF Studio added the value.

GET [BASE]/api/vi/session/[SID]/domain/[FIELD]/meta/[KEY].js

//RESPONSE:
[
  {
    "value": "apple",
    "isAdded": false
  },
  {
    "value": "banana",
    "isAdded": false
  },
  {
    "value": "orange",
    "isAdded": false
  }
]

Update Lookup Terms

Updates the terms associated with the lookup [KEY], removing any terms not contained in the set and setting all remaining values' isAdded to false.

POST [BASE]/api/vi/session/[SID]/domain/[FIELD]/meta/[KEY].js

//POST BODY:
[ 'apple','banana','carrot' ]

//RESPONSE:
{'[KEY]': 'updated' }

Updating many Lookup Terms Sets at once

Updates the terms associated with the many lookup keys at once, removing any terms not contained in the set and setting all remaining values' isAdded to false.

POST [BASE]/api/vi/session/[SID]/domain/[FIELD]/meta.js

//POST BODY:
{
  'key1':[ 'apple','banana','carrot' ],
  'key2':[ 'dog','cat','horse' ]
}

//RESPONSE:
{
  'key1': 'updated',
  'key2': 'updated' 
}

List Lookup Terms Added

List all terms added by users in DF Studio.

GET [BASE]/api/vi/session/[SID]/domain-added.js

//RESPONSE:
[
  {
    "field": "custom.subcategory",
    "meta": "fruit",
    "value": "guava"
  }
]

Global Terms

Some terms or options are global to all Assets

GET [BASE]/api/vi/session/[SID]/domain/[FIELD]/path/root.js

//RESPONSE:
[
  {
    "value": "apple",
    "isAdded": false
  },
  {
    "value": "banana",
    "isAdded": false
  },
  {
    "value": "orange",
    "isAdded": false
  }
]

Update Global Terms

Updates the terms global to DF Studio, removing any values not contained in the set and setting all remaining values' isAdded to false.

POST [BASE]/api/vi/session/[SID]/domain/[FIELD]/path/root.js

//POST BODY:
[ 'apple','banana','carrot' ]

//RESPONSE:
{'[KEY]': 'updated' }

Defining Terms with Labels

Updates the terms with labels for multiple lookup keys at once. If no Label is set for a value, then the value is shown in DF Studio.

POST [BASE]/api/vi/session/[SID]/domain/[FIELD]/meta.js

//POST BODY:
{
  'key1':[ {value:'1',label:'apple'},{value:'2',label:'banana'},{value:'3',label:'carrot'} ],
  'key2':[ 'dog','cat','horse' ]
}

//RESPONSE:
{
  'key1': 'updated',
  'key2': 'updated' 
}