Skip to content

Developers

How can we help you?

← Go back

Compilation

Compilations are a high-level catalogue entity that allows content packaging in a more “editorial” way. Some examples:

  • A compilation can gather the 4K version of all episodes of a given series.
  • Another compilation can hold all “Best of the season” episodes from all the seasons of a given TV show.

Compilations don’t belong to the catalogue hierarchy. They are kind of an external item which is able to contain other items from the catalogue and able to be linked to any level of the hierarchy.

Regarding medatada, a compilation can be configured to use different metadata groups depending on the type of compilation the user is putting together (series, versions, renditions, mixed items).

This is how a compilation looks:

<?xml version="1.0" encoding="UTF-8"?>
<compilation>
  <id type="integer">123</id>
  <name>Star Wars 4K</name>
  <external-id>SW4K</external-id>
  <metadata-groups-category>Homogeneous</metadata-groups-category>
  <tags>Action,Sci-Fi</tags>
  <acl-hash>&lt;view@everyone&gt; &lt;edit@team#141&gt; &lt;contribute@user#38&gt;</acl-hash>
  <link rel="self" href="https://movida.bebanjo.net/api/compilations/123"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/compilations/123/brands"/>
  <link rel="titles" href="https://movida.bebanjo.net/api/compilations/123/titles"/>
  <link rel="series" href="https://movida.bebanjo.net/api/compilations/123/series"/>
  <link rel="assets" href="https://movida.bebanjo.net/api/compilations/123/assets"/>
  <link rel="renditions" href="https://movida.bebanjo.net/api/compilations/123/renditions"/>
  <link rel="images" href="https://movida.bebanjo.net/api/compilations/123/images"/>
  <link rel="part_of" href="https://movida.bebanjo.net/api/title_groups/321"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/compilations/123/clips"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/compilations/123/metadata"/>
  <link rel="compilation_entries" href="https://movida.bebanjo.net/api/compilations/123/compilation_entries"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/compilations/123/credits"/>
  <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
</compilation>

{
  "resource_type": "compilation",
  "id": 123,
  "name": "Star Wars 4K",
  "external_id": "SW4K",
  "metadata_groups_category": "Homogeneous",
  "tags": "Action,Sci-Fi",
  "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#38>",
  "self_link": "https://movida.bebanjo.net/api/compilations/123",
  "brands_link": "https://movida.bebanjo.net/api/compilations/123/brands",
  "titles_link": "https://movida.bebanjo.net/api/compilations/123/titles",
  "series_link": "https://movida.bebanjo.net/api/compilations/123/series",
  "assets_link": "https://movida.bebanjo.net/api/compilations/123/assets",
  "renditions_link": "https://movida.bebanjo.net/api/compilations/123/renditions",
  "images_link": "https://movida.bebanjo.net/api/compilations/123/images",
  "part_of_link": "https://movida.bebanjo.net/api/title_groups/321",
  "clips_link": "https://movida.bebanjo.net/api/compilations/123/clips",
  "metadata_link": "https://movida.bebanjo.net/api/compilations/123/metadata",
  "compilation_entries_link": "https://movida.bebanjo.net/api/compilations/123/compilation_entries",
  "credits_link": "https://movida.bebanjo.net/api/compilations/123/credits",
  "creator_link": "https://movida.bebanjo.net/api/users/38"
}

The creator link represents the user creator of the compilation, and it will be present only when the compilation is created by a regular user, and not by an API user. This link is visible only for BeBanjo accounts configured for User Permissions.

Valid attributes

  • id (required): BeBanjo internal identifier of the compilation. It shouldn’t be provided in the creation of the resource, because BeBanjo will assign that value.

  • external-id (optional): the identifier of the compilation in the external system. If provided, it has to be unique in the scope of the company.

  • name (required): the name of the compilation.

  • tags (optional): the list of tags separated by commas of the compilation.

  • metadata_groups_category (required): the name of the compilation’s metadata groups category. A compilation can only use the metadata groups (in the compilations metadata template) matching this value.

  • acl-hash (optional): a string representation of user permissions assigned to the compilation. This property can be updated only by API users, adding or removing permissions from the list as needed.

    • Pattern: <permissionName@subjectType#subjectId>
    • Example: <contribute@team#101> <edit@everyone> <view@user#123>

    Each user permission representation const of 3 parts:

    • permissionName: the name of the Permission resource.
    • subjectType: the type of the subject being granted with permissions. Allowed values: “user” for User, “team” for Team and “everyone” when it makes reference to all users of the BeBnanjo account.
    • subjectId: the BeBanjo internal identifier of the subject.

    This attribute is only present for BeBanjo accounts configured for User Permissions.

Get a list of all compilations in the current account

Compilations are linked from the root of the API, through the link identified with the rel="compilations" attribute:

<?xml version="1.0" encoding="UTF-8"?>
<movida>
  <!-- ... -->
  <link rel="compilations" href="https://movida.bebanjo.net/api/compilations">
</movida>

{
  // ...
  "compilations_link": "https://movida.bebanjo.net/api/compilations",
  // ...
}

Following that link, we can fetch the list of compilations in the current account.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/compilations

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/compilations

<?xml version="1.0" encoding="UTF-8"?>
<compilations type="array">
  <total-entries>105</total-entries>
  <link rel="next" href="https://movida.bebanjo.net/api/compilations?page=1"/>
  <link rel="prev" href="https://movida.bebanjo.net/api/compilations?page=3"/>
  <compilation>
    <id type="integer">123</id>
    <name>Star Wars 4K</name>
    <external-id>SW4K</external-id>
    <metadata-groups-category>Homogeneous</metadata-groups-category>
    <tags>Action,Sci-Fi</tags>
    <acl-hash>&lt;view@everyone&gt; &lt;edit@team#141&gt; &lt;contribute@user#38&gt;</acl-hash>
    <link rel="self" href="https://movida.bebanjo.net/api/compilations/123"/>
    <link rel="brands" href="https://movida.bebanjo.net/api/compilations/123/brands"/>
    <link rel="titles" href="https://movida.bebanjo.net/api/compilations/123/titles"/>
    <link rel="series" href="https://movida.bebanjo.net/api/compilations/123/series"/>
    <link rel="assets" href="https://movida.bebanjo.net/api/compilations/123/assets"/>
    <link rel="renditions" href="https://movida.bebanjo.net/api/compilations/123/renditions"/>
    <link rel="images" href="https://movida.bebanjo.net/api/compilations/123/images"/>
    <link rel="part_of" href="https://movida.bebanjo.net/api/title_groups/321"/>
    <link rel="clips" href="https://movida.bebanjo.net/api/compilations/123/clips"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/compilations/123/metadata"/>
    <link rel="compilation_entries" href="https://movida.bebanjo.net/api/compilations/123/compilation_entries"/>
    <link rel="credits" href="https://movida.bebanjo.net/api/compilations/123/credits"/>
    <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
  </compilation>
  <compilation>
    <id type="integer">124</id>
    <name>Best of NCIS</name>
    <external-id>BESTNCS</external-id>
    <tags>Action,Drama</tags>
    <acl-hash>&lt;view@everyone&gt; &lt;edit@team#141&gt; &lt;contribute@user#43&gt;</acl-hash>
    <link rel="self" href="https://movida.bebanjo.net/api/compilations/124"/>
    <link rel="brands" href="https://movida.bebanjo.net/api/compilations/124/brands"/>
    <link rel="titles" href="https://movida.bebanjo.net/api/compilations/124/titles"/>
    <link rel="series" href="https://movida.bebanjo.net/api/compilations/124/series"/>
    <link rel="assets" href="https://movida.bebanjo.net/api/compilations/124/assets"/>
    <link rel="renditions" href="https://movida.bebanjo.net/api/compilations/124/renditions"/>
    <link rel="images" href="https://movida.bebanjo.net/api/compilations/124/images"/>
    <link rel="part_of" href="https://movida.bebanjo.net/api/title_groups/321"/>
    <link rel="clips" href="https://movida.bebanjo.net/api/compilations/124/clips"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/compilations/124/metadata"/>
    <link rel="compilation_entries" href="https://movida.bebanjo.net/api/compilations/124/compilation_entries"/>
    <link rel="credits" href="https://movida.bebanjo.net/api/compilations/124/credits"/>
    <link rel="creator" href="https://movida.bebanjo.net/api/users/43"/>
  </compilation>
  <!-- ... -->
</compilations>

{
  "total_entries": 105,
  "prev_link": "https://movida.bebanjo.net/api/compilations?page=1",
  "next_link": "https://movida.bebanjo.net/api/compilations?page=3",
  "entries": [
    {
      "resource_type": "compilation",
      "id": 123,
      "name": "Star Wars 4K",
      "external_id": "SW4K",
      "metadata_groups_category": "Homogeneous",
      "tags": "Action,Sci-Fi",
      "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#38>",
      "self_link": "https://movida.bebanjo.net/api/compilations/123",
      "brands_link": "https://movida.bebanjo.net/api/compilations/123/brands",
      "titles_link": "https://movida.bebanjo.net/api/compilations/123/titles",
      "series_link": "https://movida.bebanjo.net/api/compilations/123/series",
      "assets_link": "https://movida.bebanjo.net/api/compilations/123/assets",
      "renditions_link": "https://movida.bebanjo.net/api/compilations/123/renditions",
      "images_link": "https://movida.bebanjo.net/api/compilations/123/images",
      "part_of_link": "https://movida.bebanjo.net/api/title_groups/321",
      "clips_link": "https://movida.bebanjo.net/api/compilations/123/clips",
      "metadata_link": "https://movida.bebanjo.net/api/compilations/123/metadata",
      "compilation_entries_link": "https://movida.bebanjo.net/api/compilations/123/compilation_entries",
      "credits_link": "https://movida.bebanjo.net/api/compilations/123/credits",
      "creator_link": "https://movida.bebanjo.net/api/users/38"
    },
    {
      "resource_type": "compilation",
      "id": 124,
      "name": "Best of NCIS",
      "external_id": "BESTNCS",
      "tags": "Action,Drama",
      "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#43>",
      "self_link": "https://movida.bebanjo.net/api/compilations/124",
      "brands_link": "https://movida.bebanjo.net/api/compilations/124/brands",
      "titles_link": "https://movida.bebanjo.net/api/compilations/124/titles",
      "series_link": "https://movida.bebanjo.net/api/compilations/124/series",
      "assets_link": "https://movida.bebanjo.net/api/compilations/124/assets",
      "renditions_link": "https://movida.bebanjo.net/api/compilations/124/renditions",
      "images_link": "https://movida.bebanjo.net/api/compilations/124/images",
      "part_of_link": "https://movida.bebanjo.net/api/title_groups/321",
      "clips_link": "https://movida.bebanjo.net/api/compilations/124/clips",
      "metadata_link": "https://movida.bebanjo.net/api/compilations/124/metadata",
      "compilation_entries_link": "https://movida.bebanjo.net/api/compilations/124/compilation_entries",
      "credits_link": "https://movida.bebanjo.net/api/compilations/124/credits",
      "creator_link": "https://movida.bebanjo.net/api/users/43"
    },
    // ...
  ]
}

Note: This is a paginated resource. Only 50 compilations will be included on each page by default, but you can override this default by using the per_page parameter described in the next sections. The total-entries attribute will indicate the total number of entries and the links rel="next" and rel="prev" should be used to get the next and the previous pages.

You can filter the list of compilations returned using the following attributes:

  • external_id: When provided, it will return only the compilation with the given external ID when provided.
  • per_page: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50.

Get a single compilation given its URL

The self link of a compilation contains a URL that will allow us to fetch that individual compilation:

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/compilations/123

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/compilations/123

<?xml version="1.0" encoding="UTF-8"?>
<compilation>
  <id type="integer">123</id>
  <name>Star Wars 4K</name>
  <external-id>SW4K</external-id>
  <metadata-groups-category>Homogeneous</metadata-groups-category>
  <tags>Action,Sci-Fi</tags>
  <acl-hash>&lt;view@everyone&gt; &lt;edit@team#141&gt; &lt;contribute@user#38&gt;</acl-hash>
  <link rel="self" href="https://movida.bebanjo.net/api/compilations/123"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/compilations/123/brands"/>
  <link rel="titles" href="https://movida.bebanjo.net/api/compilations/123/titles"/>
  <link rel="series" href="https://movida.bebanjo.net/api/compilations/123/series"/>
  <link rel="assets" href="https://movida.bebanjo.net/api/compilations/123/assets"/>
  <link rel="renditions" href="https://movida.bebanjo.net/api/compilations/123/renditions"/>
  <link rel="images" href="https://movida.bebanjo.net/api/compilations/123/images"/>
  <link rel="part_of" href="https://movida.bebanjo.net/api/title_groups/321"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/compilations/123/clips"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/compilations/123/metadata"/>
  <link rel="compilation_entries" href="https://movida.bebanjo.net/api/compilations/123/compilation_entries"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/compilations/123/credits"/>
  <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
</compilation>

{
  "resource_type": "compilation",
  "id": 123,
  "name": "Star Wars 4K",
  "external_id": "SW4K",
  "metadata_groups_category": "Homogeneous",
  "tags": "Action,Sci-Fi",
  "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#38>",
  "self_link": "https://movida.bebanjo.net/api/compilations/123",
  "brands_link": "https://movida.bebanjo.net/api/compilations/123/brands",
  "titles_link": "https://movida.bebanjo.net/api/compilations/123/titles",
  "series_link": "https://movida.bebanjo.net/api/compilations/123/series",
  "assets_link": "https://movida.bebanjo.net/api/compilations/123/assets",
  "renditions_link": "https://movida.bebanjo.net/api/compilations/123/renditions",
  "images_link": "https://movida.bebanjo.net/api/compilations/123/images",
  "part_of_link": "https://movida.bebanjo.net/api/title_groups/321",
  "clips_link": "https://movida.bebanjo.net/api/compilations/123/clips",
  "metadata_link": "https://movida.bebanjo.net/api/compilations/123/metadata",
  "compilation_entries_link": "https://movida.bebanjo.net/api/compilations/123/compilation_entries",
  "credits_link": "https://movida.bebanjo.net/api/compilations/123/credits",
  "creator_link": "https://movida.bebanjo.net/api/users/38"
}

Create a new compilation

To create a compilation, you just need to POST the proper XML/JSON representation of a compilation (similar to the ones you get when fetching) to the URL that you can find in the link rel="compilations" of the root of the API.

For example, this POST would create a compilation: we’ll use curl’s @ option, which reads the data that is to be posted to the URL from a file.

$ cat payload.xml

$ cat payload.json

<?xml version="1.0" encoding="UTF-8"?>
<compilation>
  <name>Star Wars 4K</name>
  <metadata-groups-category>Homogeneous</metadata-groups-category>
</compilation>

{
  "name": "Star Wars 4K",
  "metadata_groups_category": "Homogeneous"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @payload.xml "https://movida.bebanjo.net/api/compilations"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @payload.json "https://movida.bebanjo.net/api/compilations"

BeBanjo will return the full XML/JSON of the compilation just created:

<?xml version="1.0" encoding="UTF-8"?>
<compilation>
  <id type="integer">123</id>
  <name>Star Wars 4K</name>
  <metadata-groups-category>Homogeneous</metadata-groups-category>
  <acl-hash nil="true"/>
  <link rel="self" href="https://movida.bebanjo.net/api/compilations/123"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/compilations/123/brands"/>
  <link rel="titles" href="https://movida.bebanjo.net/api/compilations/123/titles"/>
  <link rel="series" href="https://movida.bebanjo.net/api/compilations/123/series"/>
  <link rel="assets" href="https://movida.bebanjo.net/api/compilations/123/assets"/>
  <link rel="renditions" href="https://movida.bebanjo.net/api/compilations/123/renditions"/>
  <link rel="images" href="https://movida.bebanjo.net/api/compilations/123/images"/>
  <link rel="part_of" href="https://movida.bebanjo.net/api/title_groups/321"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/compilations/123/clips"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/compilations/123/metadata"/>
  <link rel="compilation_entries" href="https://movida.bebanjo.net/api/compilations/123/compilation_entries"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/compilations/123/credits"/>
  <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
</compilation>

{
  "resource_type": "compilation",
  "id": 123,
  "name": "Star Wars 4K",
  "metadata_groups_category": "Homogeneous",
  "acl_hash": null,
  "self_link": "https://movida.bebanjo.net/api/compilations/123",
  "brands_link": "https://movida.bebanjo.net/api/compilations/123/brands",
  "titles_link": "https://movida.bebanjo.net/api/compilations/123/titles",
  "series_link": "https://movida.bebanjo.net/api/compilations/123/series",
  "assets_link": "https://movida.bebanjo.net/api/compilations/123/assets",
  "renditions_link": "https://movida.bebanjo.net/api/compilations/123/renditions",
  "images_link": "https://movida.bebanjo.net/api/compilations/123/images",
  "part_of_link": "https://movida.bebanjo.net/api/title_groups/321",
  "clips_link": "https://movida.bebanjo.net/api/compilations/123/clips",
  "metadata_link": "https://movida.bebanjo.net/api/compilations/123/metadata",
  "compilation_entries_link": "https://movida.bebanjo.net/api/compilations/123/compilation_entries",
  "credits_link": "https://movida.bebanjo.net/api/compilations/123/credits",
  "creator_link": "https://movida.bebanjo.net/api/users/38"
}

Updating a compilation

You can update an existing compilation sending a PUT request to the URL of the compilation (that you can get from its link rel="self"). You only need to include those attributes of the compilation that you wish to update:

$ cat payload.xml

$ cat payload.json

<?xml version="1.0" encoding="UTF-8"?>
<compilation>
  <external-id>SW4K</external-id>
</compilation>

{
  "external_id": "SW4K"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @payload.xml "https://movida.bebanjo.net/api/compilations/123"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d @payload.json "https://movida.bebanjo.net/api/compilations/123"

BeBanjo will return the full XML/JSON of the compilation just updated:

<?xml version="1.0" encoding="UTF-8"?>
<compilation>
  <id type="integer">123</id>
  <name>Star Wars 4K</name>
  <external-id>SW4K</external-id>
  <acl-hash nil="true"/>
  <link rel="self" href="https://movida.bebanjo.net/api/compilations/123"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/compilations/123/brands"/>
  <link rel="titles" href="https://movida.bebanjo.net/api/compilations/123/titles"/>
  <link rel="series" href="https://movida.bebanjo.net/api/compilations/123/series"/>
  <link rel="assets" href="https://movida.bebanjo.net/api/compilations/123/assets"/>
  <link rel="renditions" href="https://movida.bebanjo.net/api/compilations/123/renditions"/>
  <link rel="images" href="https://movida.bebanjo.net/api/compilations/123/images"/>
  <link rel="part_of" href="https://movida.bebanjo.net/api/title_groups/321"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/compilations/123/clips"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/compilations/123/metadata"/>
  <link rel="compilation_entries" href="https://movida.bebanjo.net/api/compilations/123/compilation_entries"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/compilations/123/credits"/>
  <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
</compilation>

{
  "resource_type": "compilation",
  "id": 123,
  "name": "Star Wars 4K",
  "external_iod": "SW4K",
  "metadata_groups_category": "Homogeneous",
  "acl_hash": null,
  "self_link": "https://movida.bebanjo.net/api/compilations/123",
  "brands_link": "https://movida.bebanjo.net/api/compilations/123/brands",
  "titles_link": "https://movida.bebanjo.net/api/compilations/123/titles",
  "series_link": "https://movida.bebanjo.net/api/compilations/123/series",
  "assets_link": "https://movida.bebanjo.net/api/compilations/123/assets",
  "renditions_link": "https://movida.bebanjo.net/api/compilations/123/renditions",
  "images_link": "https://movida.bebanjo.net/api/compilations/123/images",
  "part_of_link": "https://movida.bebanjo.net/api/title_groups/321",
  "clips_link": "https://movida.bebanjo.net/api/compilations/123/clips",
  "metadata_link": "https://movida.bebanjo.net/api/compilations/123/metadata",
  "compilation_entries_link": "https://movida.bebanjo.net/api/compilations/123/compilation_entries",
  "credits_link": "https://movida.bebanjo.net/api/compilations/123/credits",
  "creator_link": "https://movida.bebanjo.net/api/users/38"
}

Deleting a compilation

You can also delete a compilation using a DELETE request to the compilation URL:

$ curl --digest -u robot_user:password -X DELETE "https://movida.bebanjo.net/api/compilations/123"

$ curl --digest -u robot_user:password -H "Accept: application/json" -X DELETE "https://movida.bebanjo.net/api/compilations/123"

Note: Deleting a compilation won’t delete its contents in cascade.