Resource - loc:locations

loc:locations is a resource that provides links to functionality regarding a folder structure to be displayed for a system. You can query the loc:locations resource by getting the service root info. and following the loc:locations link.

The loc:locations resource may contain the following link relations:

loc:item-by-id

Returns the item identified by the given identifier. The item can be a folder or a non-folder item. The result is an loc:item resource.

HTTP Method

GET

Template Variables

  • id (mandatory): the id of the item

  • attributes: a comma separated list of system-specific attribute names, which will be put into the item representation (into the "attributes" property) of the response. If comma (',') is part of an attribute’s name, it needs to be escaped when used with the query parameter "attributes". E.g. the attribute name "escape,me" must be passed as "escape\,me". The loc:items in the response will contain the extra top level (sibling to "common") property "attributes", which contains an array of attributes having one element per attribute: "attributes": [ { "name": "comment", "value": "Deja vu" }, { "name": "RIGHTS_INDICATOR", "value": "0" } …​]. For more information on the response, see loc:item.

    • MAM:

      • Folders itself do not support attributes, but the specification of attributes on folders will fill the attributes of the folder-items.

      • "attributes" is transitive: If a list of attributes was applied on a folder request, the links to further folders contained in the response will also have this attribute list in their URLs.

      • Individual elements of the "attributes" array do only provide the properties "name" and "value".

      • Attribute names are handled in a case-insensitive manner.

    • PAM:

      • Attribute names are handled in a case-insensitive manner.

  • offset: (only for folder items) the offset within the search results. This parameter is used for paging. If missing or invalid (less than 0), the default is 0, meaning that the results are returned beginning with the first element.

  • limit: (only for folder items) the maximum number of matches to return. This parameter is used for paging.

    • MAM:

      • If missing or invalid (less or equal than 0, or higher than the maximum value of 1000), the default is 100.

  • sort: (only for folder items) the sort order. It accepts a comma separated list of sort descriptors, which are applied on enumerating items in the collection of the requested location. The order of the sort descriptors in the comma separated list corresponds to the order, in which the descriptors are applied as sort criteria. An individual sort descriptor consists of an optionally prefixing '+'/'-' character to indicate ascending ('\+', the default) or descending ('-') order, followed by the name of an attribute, or the keyword "folder". The keyword "folder" sorts for the type of items, i.e. the "base"'s property "type", it can esp. be used to sort for folder-items right before or after non-folder items. The "folder" sort descriptor can be front loaded to other sort descriptors to simulate Windows Explorer’s sort behavior, e.g. "folder,name", "-folder,-name" or "folder,created". If comma (',') is part of a sort descriptor’s attribute name, it needs to be escaped. E.g. the attribute name "escape,me" must be passed as "escape\,me". If missing, the default is sorting by "folder" and "name" in ascending order (folder,name).

    • PAM

      • Sort descriptors are handled in a case-sensitive manner.

      • The sort descriptor "folder" is supported since 2018.6.

    • MAM

      • Sort descriptors are handled in a case-insensitive manner.

  • filter: (only for folder items) accepts a comma separated list of filter descriptors, which are applied on requesting the specified location. If filter is not given or is empty, then the service returns a default set of items; typically the folders and asset that is user is supposed to see. If the list is not empty, then the service returns the union of all matching items. Filter names are case-insensitive.

    • Typical filters:

      • item-type-folder: returns folders

      • item-type-asset: returns assets

      • item-type-all: returns all items in the folder, including items that are usually not visible to a user, like, for example, referenced assets in PAM

      • item-type-referenced-asset (PAM only): returns assets that are not checked-in directly, but are referenced in other assets like sequences

    • The response of a filtered location influences the paging, in such that the property "totalElements" represents the count of items after the filter was applied.

    • If comma (',') is part of a filter descriptor, it needs to be escaped when used with the query parameter "filter". E.g. the filter descriptor "escape,me" must be passed as "escape\,me".

  • embed: a comma separated list of resources to be embedded into the resulting resource

    • thumb: embeds aa:thumb resources

    • path-to-root: embeds loc:path-to-root resources

    • path: must be used together with path-to-root; embeds the loc:path resources that reference the folders into the returned loc:path-to-root resources

      • PAM:

    • thumb: embeds aa:thumbresources

    • icon: embeds aa:icon resources

    • path: embeds loc:path resource

  • lang: specifies the language/locale for attribute values in the referenced asset, if supported. The value must be a must be a valid IETF BCP 47 language tag, if is left away, only "en" labels and tooltips will be in the result. If, for the specified language tag, no labels and tooltips could be found, only "en" labels and tooltips will be in the result. this behavior will be changed

    • MAM:

      • L10n is applied for legallist and thesaurus attributes.

Query Parameters

None

loc:root-item

Returns the root item of a folder structure for the system. The root item should be a folder item. The link requests the first page of the sub items in the folder, with the default page size of 100 items.

The result is an loc:item resource.

HTTP Method

GET

Template Variables

None

Query Parameters

None

loc:update-item

Will respond with the updated item’s resource.

HTTP Method

PATCH

System Specific Extensions

PAM

pa:location-item-by-moniker

Returns the item identified by the provided PAM moniker (sometimes used by MediaCentral | UX APIs). When used, this call can serve as a bridge between legacy PAM APIs and CTMS. The result is a loc:item resource.

HTTP Method

GET

Template Variables

  • moniker (mandatory): The (URL encoded) PAM Moniker.

Query Parameters

None

Response

The result is an item resource, representing the requested item. See Resource - Location Item loc:item.

Response Codes

  • 200 "OK" in case of success

  • 404 "Not Found"

MAM

ma:create-folder-at-id

Creates a new folder under the parent folder, which is specified by the passed id. The result is an item resource, representing the created folder. See Resource - Location Item loc:item. The type of the link defines the expected format. of the request body.

Multiple folders of the same name are allowed to exist side by side.

The name of a folder may not exceed 256 characters.

HTTP Method

POST

Template Variables

  • id (mandatory): the id of the parent folder , under which the new folder should be created

Query Parameters

None

Request Body

{"common": {"name": "ExampleFolderName"}}

Response

The result is an item resource, representing the created folder. See Resource - Location Item loc:item.

Response Codes

  • 200 "OK" in case of success

  • 400 "Bad Request"

  • 404 "Not Found"

  • 403 "Forbidden"

Example

{
  "_links": {
    "curies": [
      {
        "href": "http://services.avid.com/apis/locations/{rel}",
        "name": "loc",
        "templated": true
      }
    ],
    "self": {
      "href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations"
    },
    "loc:root-item": {
      "href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/folders/1"
    }
  }
}

PAM

{
    "base": {
        "systemID": "realmId",
        "systemType": "interplay-pam"
    },
    "_links": {
        "curies": {
            "name": "loc",
            "href": "http://services.avid.com/apis/locations/{rel}",
            "templated": true
        },
        "self": {
            "href": "https://upstream/apis/avid.pam;version=2;realm=realmId/locations"
        },
        "loc:root-item": {
            "href": "https://upstream/apis/avid.pam;version=2;realm=realmId/locations/folders/%2F?offset=0&limit=25"
        },
        "loc:item-by-id": {
            "href": "https://upstream/apis/avid.pam;version=2;realm=realmId/locations/items/{id}",
            "templated": true
        },
        "pa:location-item-by-moniker": {
            "href": "https://upstream/apis/avid.pam;version=2;realm=realmId/location-item-by-moniker/{moniker}",
            "templated": true
        }
    }
}