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 requesting the specified location. The order of the sort descriptors in the comma separated list corresponds to the order, in which the descriptor are applied as sort criteria. An individual sort descriptor consists of an optional prefixed /- sign to indicate (, the default) ascending or (-) descending order, followed by the name of an attribute. If comma (',') is part of a sort descriptor’s attribute name, it needs to be escaped when used with the query parameter "sort". E.g. the attribute name "escape,me" must be passed as "escape\,me". If missing, the default is sorting by name in ascending order.

    • PAM

      • Sort descriptors are handled in a case sensitive manner.

    • 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:folder-by-id

Returns the folder identified by the given identifier. The result is an loc:item resource.

This method is obsolete. You should use loc:item-by-id instead.

HTTP Method

GET

Template Variables

  • id (mandatory): the ID of the folder

  • offset: 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: 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: the sort order. It accepts a comma separated list of sort descriptors, which are applied on requesting the specified location. The order of the sort descriptors in the comma separated list corresponds to the order, in which the descriptor are applied as sort criteria. An individual sort descriptor consists of an optional prefixed /- sign to indicate (, the default) ascending or (-) descending order, followed by the name of an attribute. If comma (',') is part of a sort descriptor’s attribute name, it needs to be escaped when used with the query parameter "sort". E.g. the attribute name "escape,me" must be passed as "escape\,me". If missing, the default is sorting by name in ascending order.

    • PAM

      • Sort descriptors are handled in a case sensitive manner.

    • MAM

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

  • filter: accepts a comma separated list of filter descriptors, which are applied on requesting the specified location. 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".

    • MAM

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

      • Filter descriptors will be applied in the order they are written.

      • Filter descriptor "item-type-folder". If applied, it leads to only having folder-items in the response.

      • Filter descriptor "item-type-referenced-object". If applied, it leads to only having non-folder-items in the response.

    • PAM

      • Filter descriptor "item-type-folder". If applied, it leads to only having folder-items in the response.

      • Filter descriptor "item-type-referenced-object". If applied, it leads to only having non-folder-items in the response.

  • 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.

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

    • thumb: embeds aa:thumb resources <<<<<<< HEAD

    • 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

    • icon: embeds aa:icon resources

<<<<<<< HEAD * path: embeds loc:path resources (in the "loc:path" property) * path: must be used together with path-to-root, embeds the items of the loc:path’s subpaths into the embedded path-to-root’s resource PAM: * thumb: embeds aa:thumbresources * icon: embeds aa:icon resources * path: embeds loc:path resource not implemented!

  • 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

  • icon: embeds aa:icon resources >>>>>>> cloud-ux-1.0 >>>>>>> master

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:root-item-templated

Templated link to the root item of a folder structure for the system. The root item should be a folder item.

The result is an loc:item resource.

HTTP Method

GET

Template Variables

None

Query Parameters

  • offset: 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: 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: the sort order. It accepts a comma separated list of sort descriptors, which are applied on requesting the specified location. The order of the sort descriptors in the comma separated list corresponds to the order, in which the descriptor are applied as sort criteria. An individual sort descriptor consists of an optional prefixed /- sign to indicate (, the default) ascending or (-) descending order, followed by the name of an attribute. If comma (',') is part of a sort descriptor’s attribute name, it needs to be escaped when used with the query parameter "sort". E.g. the attribute name "escape,me" must be passed as "escape\,me". If missing, the default is sorting by name in ascending order. (question) Jli: PAM server don’t support sort, it need to get all elements before sorting it, optional?. (question) IMHO it is optional. In MAM we also have to get all items into the CTC and then sort it.

    • PAM

      • Sort descriptors are handled in a case sensitive manner.

    • MAM

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

  • filter: accepts a comma separated list of filter descriptors, which are applied on requesting the specified location. 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".

    • MAM

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

      • Filter descriptors will be applied in the order they are written.

      • Filter descriptor "item-type-folder". If applied, it leads to only having folder-items in the response.

      • Filter descriptor "item-type-referenced-object". If applied, it leads to only having non-folder-items in the response.

    • PAM

      • Filter descriptor "item-type-folder". If applied, it leads to only having folder-items in the response.

      • Filter descriptor "item-type-referenced-object". If applied, it leads to only having non-folder-items in the response.

  • 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 Resource - Location Item loc:item.

    • MAM:

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

      • "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.

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

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

    • PAM:

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

loc:update-folder-by-id

Updates a folder identified by the given identifier.

MAM:

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

PATCH

Template Variables

  • id (mandatory): id of the folder

Query Parameters

None

Request Body

{"common": {"name": "NEW_FolderName"}}

Response Codes

  • 200 "OK" in case of success

  • 400 "Bad Request"

  • 404 "Not Found"

  • 403 "Forbidden"

loc:update-item

Will respond with the updated item’s resource.

HTTP Method

PATCH

loc:delete-folder-by-id

Deletes a folder identified by the given identifier.

iNEWS: Only empty folder can be deleted

PAM: see pa:delete-folder-by-path

HTTP Method

DELETE

Template Variables

  • id (mandatory): id of the folder

Query Parameters

None

Response Codes

  • 204 "No Content" in case of success

  • 404 "Not Found"

  • 403 "Forbidden"

System Specific Extensions

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:item-by-id": {
       "href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/items/{id}",
      "templated": true
    },
    "loc:folder-by-id": {
      "href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/folders/{id}",
      "templated": true
    },
    "loc:root-item": {
      "href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/folders/1"
    },
    "loc:root-item-templated": {
      "href": "https://upstream/apis/avid.mam.assets.access;version=0;realm=BEEF/locations/folders/1{?offset,limit,sort,filter,attributes}",
      "templated": true
    }
  }
}
{
  "base": {
    "systemType": "interplay-pam",
    "systemID": "a51-wg6-eng1"
  },
  "_links": {
    "self": {
      "href": "http://api.cloudbox.cloudbox:8080/apis/avid.pam;realm=global;version=0/locations"
    },
    "loc:root-item": {
      "href": "http://api.cloudbox.cloudbox:8080/apis/avid.pam;realm=global;version=0/locations/folders/*?offset=0&limit=25"
    },
    "loc:root-item-template": {
      "href": "http://api.cloudbox.cloudbox:8080/apis/avid.pam;realm=global;version=0/locations/folders/*{?offset,limit}",
      "templated": true
    },
    "loc:folder-by-id": {
      "href": "http://api.cloudbox.cloudbox:8080/apis/avid.pam;realm=global;version=0/locations/folders/{folderid}{?offset,limit}",
      "templated": true
    },
    "pa:create-folder-by-path": {
      "href": "http://api.cloudbox.cloudbox:8080/apis/avid.pam;realm=global;version=0/locations/folders/{path}?folderName={folderName}",
      "templated": true
    },
    "pa:delete-folder-by-path": {
      "href": "http://api.cloudbox.cloudbox:8080/apis/avid.pam;realm=global;version=0/locations/folders/{path}?folderName={folderName}",
      "templated": true
    },
    "curies": [
      {
        "name": "pa",
        "href": "http://services.avid.com/apis/pam/assets/{rel}",
        "templated": true
      },
      {
        "name": "loc",
        "href": "http://services.avid.com/apis/locations/{rel}",
        "templated": true
      }
    ]
  }
}