Developers

How can we help you?

Franchise

A franchise is, above brands, the higher level entity in the hierarchy of BeBanjo’s Catalogue. A franchise is an entity that groups Brands and Features. For example, a franchise called “Star Wars” would contain the “Skywalker Saga” brand, along with the “Rogue One” feature, the “The Mandalorian” brand, etc.

This is how a franchise looks through the API:

<?xml version="1.0" encoding="UTF-8"?>
<franchise>
  <id type="integer">123</id>
  <name>Star Wars</name>
  <name-en>Star Wars</name-en>
  <external-id>SW</external-id>
  <tags>Action,Drama</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/franchises/123"/>
  <link rel="titles" href="https://movida.bebanjo.net/api/franchises/123/titles"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/franchises/123/brands"/>
  <link rel="images" href="https://movida.bebanjo.net/api/franchises/123/images"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/franchises/123/credits"/>
  <link rel="licensor" href="https://movida.bebanjo.net/api/licensors/352"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/franchises/123/metadata"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/franchises/123/clips"/>
  <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
</franchise>

{
  "resource_type": "franchise",
  "id": 123,
  "name": "Star Wars",
  "external_id": "SW",
  "tags": "Action,Drama",
  "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#38>",
  "self_link": "https://movida.bebanjo.net/api/franchises/123",
  "titles_link": "https://movida.bebanjo.net/api/franchises/123/titles",
  "brands_link": "https://movida.bebanjo.net/api/franchises/123/brands",
  "images_link": "https://movida.bebanjo.net/api/franchises/123/images",
  "credits_link": "https://movida.bebanjo.net/api/franchises/123/credits",
  "metadata_link": "https://movida.bebanjo.net/api/franchises/123/metadata",
  "licensor_link": "https://movida.bebanjo.net/api/licensors/352",
  "clips_link": "https://movida.bebanjo.net/api/franchises/123/clips",
  "creator_link": "https://movida.bebanjo.net/api/users/38"
}

The creator link is pointing to the user creator of the franchise, and the link will only be present if the creator of the franchise is a regular user, and not an API user. This link is visible only for BeBanjo accounts configured for User Permissions.

Valid attributes

id (required): BeBanjo internal identifier of the franchise. It shouldn’t be provided in the creation of the resource, because BeBanjo will assign that value.
external-id (optional): the identifier of the franchise in the external system. If provided, it has to be unique in the scope of the company.
name (required): the name of the franchise.
tags (optional): the list of tags separated by commas of the franchise.
acl-hash (optional): a string representation of user permissions assigned to the franchise. 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 franchises in the current account

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

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

{
  // ...
  "franchises_link": "https://movida.bebanjo.net/api/franchises",
  // ...
}

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<franchises type="array">
  <total-entries>2120</total-entries>
  <link rel="next" href="https://movida.bebanjo.net/api/franchises?page=1"/>
  <link rel="prev" href="https://movida.bebanjo.net/api/franchises?page=3"/>
  <franchise>
    <id type="integer">123</id>
    <name>Star Wars</name>
    <external-id>SW</external-id>
    <tags>Action,Drama</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/franchises/123"/>
    <link rel="brands" href="https://movida.bebanjo.net/api/franchises/123/brands"/>
    <link rel="titles" href="https://movida.bebanjo.net/api/franchises/123/titles"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/franchises/123/metadata"/>
    <link rel="images" href="https://movida.bebanjo.net/api/franchises/123/images"/>
    <link rel="licensor" href="https://movida.bebanjo.net/api/licensor/352"/>
    <link rel="clips" href="https://movida.bebanjo.net/api/franchises/123/clips"/>
    <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
  </franchise>
  <franchise>
    <id type="integer">124</id>
    <name>NCIS</name>
    <external-id>NCS</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/franchises/124"/>
    <link rel="brands" href="https://movida.bebanjo.net/api/franchises/124/brands"/>
    <link rel="titles" href="https://movida.bebanjo.net/api/franchises/124/titles"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/franchises/124/metadata"/>
    <link rel="images" href="https://movida.bebanjo.net/api/franchises/124/images"/>
    <link rel="licensor" href="https://movida.bebanjo.net/api/licensor/353"/>
    <link rel="clips" href="https://movida.bebanjo.net/api/franchises/124/clips"/>
    <link rel="creator" href="https://movida.bebanjo.net/api/users/43"/>
  </franchise>
  <!-- ... -->
</franchises>

{
  "total_entries": 2120,
  "prev_link": "https://movida.bebanjo.net/api/franchises?page=1",
  "next_link": "https://movida.bebanjo.net/api/franchises?page=3",
  "entries": [
    {
      "resource_type": "franchise",
      "id": 123,
      "name": "Star Wars",
      "external_id": "SW",
      "tags": "Action,Drama",
      "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#38>",
      "self_link": "https://movida.bebanjo.net/api/franchises/123",
      "brands_link": "https://movida.bebanjo.net/api/franchises/123/brands",
      "titles_link": "https://movida.bebanjo.net/api/franchises/123/titles",
      "metadata_link": "https://movida.bebanjo.net/api/franchises/123/metadata",
      "images_link": "https://movida.bebanjo.net/api/franchises/123/images",
      "licensor_link": "https://movida.bebanjo.net/api/licensors/352",
      "clips_link": "https://movida.bebanjo.net/api/franchises/123/clips",
      "creator_link": "https://movida.bebanjo.net/api/users/38"
    },
    {
      "resource_type": "franchise",
      "id": 124,
      "name": "NCIS",
      "external_id": "NCS",
      "tags": "Action,Drama",
      "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#43>",
      "self_link": "https://movida.bebanjo.net/api/franchises/124",
      "brands_link": "https://movida.bebanjo.net/api/franchises/124/brands",
      "titles_link": "https://movida.bebanjo.net/api/franchises/124/titles",
      "titles_link": "https://movida.bebanjo.net/api/franchises/124/titles",
      "metadata_link": "https://movida.bebanjo.net/api/franchises/124/metadata",
      "images_link": "https://movida.bebanjo.net/api/franchises/124/images",
      "licensor_link": "https://movida.bebanjo.net/api/licensors/353",
      "clips_link": "https://movida.bebanjo.net/api/franchises/124/clips",
      "creator_link": "https://movida.bebanjo.net/api/users/43"
    },
    // ...
  ]
}

Note: This is a paginated resource. By default, only 50 franchises will be included in each page but you can override this default by using the per_page parameter described in the next section. 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 franchises returned using the following attributes:

external_id: It will return only the franchise with the given external ID (if any).
per_page: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50.

Get a single franchise given its URL

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<franchise>
  <id type="integer">123</id>
  <name>Star Wars</name>
  <external-id>SW</external-id>
  <tags>Action,Drama</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/franchises/123"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/franchises/123/brands"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/franchises/123/metadata"/>
  <link rel="images" href="https://movida.bebanjo.net/api/franchises/123/images"/>
  <link rel="licensor" href="https://movida.bebanjo.net/api/licensor/352"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/franchises/123/clips"/>
  <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
</franchise>

{
  "resource_type": "franchise",
  "id": 123,
  "name": "Star Wars",
  "external_id": "SW",
  "tags": "Action,Drama",
  "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#38>",
  "self_link": "https://movida.bebanjo.net/api/franchises/123",
  "brands_link": "https://movida.bebanjo.net/api/franchises/123/brands",
  "titles_link": "https://movida.bebanjo.net/api/franchises/123/titles",
  "metadata_link": "https://movida.bebanjo.net/api/franchises/123/metadata",
  "images_link": "https://movida.bebanjo.net/api/franchises/123/images",
  "licensor_link": "https://movida.bebanjo.net/api/licensors/352",
  "clips_link": "https://movida.bebanjo.net/api/franchises/123/clips",
  "creator_link": "https://movida.bebanjo.net/api/users/38"
}

Create a new franchise

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

For example, this POST would create a franchise: (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"?>
<franchise>
  <name>FBI</name>
  <external-id>FB</external-id>
  <link rel="licensor" href="https://movida.bebanjo.net/api/licensors/354"/>
</franchise>

{
  "name": "FBI",
  "external_id": "FB",
  "licensor_link": "https://movida.bebanjo.net/api/licensors/354"
}

Note: The licensor URL must be of one licensor that already exists in the system, licensor URL is optional. See how to create licensors in the [[BeBanjo Resource: Licensor]] page.

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

$ 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/franchises"

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

<?xml version="1.0" encoding="UTF-8"?>
<franchise>
  <id type="integer">125</id>
  <name>FBI</name>
  <external-id>FB</external-id>
  <tags></tags>
  <acl-hash nil="true"></acl-hash>
  <link rel="self" href="https://movida.bebanjo.net/api/franchises/125"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/franchises/125/brands"/>
  <link rel="titles" href="https://movida.bebanjo.net/api/franchises/125/titles"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/franchises/125/metadata"/>
  <link rel="images" href="https://movida.bebanjo.net/api/franchises/125/images"/>
  <link rel="licensor" href="https://movida.bebanjo.net/api/licensors/354"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/franchises/125/clips"/>
</franchise>

{
  "resource_type": "franchise",
  "id": 125,
  "name": "FBI",
  "external_id": "FB",
  "tags": "",
  "acl_hash": null,
  "self_link": "https://movida.bebanjo.net/api/franchises/125",
  "brands_link": "https://movida.bebanjo.net/api/franchises/125/brands",
  "titles_link": "https://movida.bebanjo.net/api/franchises/125/titles",
  "metadata_link": "https://movida.bebanjo.net/api/franchises/125/metadata",
  "images_link": "https://movida.bebanjo.net/api/franchises/125/images",
  "licensor_link": "https://movida.bebanjo.net/api/licensors/354",
  "clips_link": "https://movida.bebanjo.net/api/franchises/125/clips"
}

Updating a franchise

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

$ cat payload.xml

$ cat payload.json

<?xml version="1.0" encoding="UTF-8"?>
<franchise>
  <name>FBI</name>
</franchise>

{
  "name": "FBI"
}

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

$ 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/franchises/125"

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

<?xml version="1.0" encoding="UTF-8"?>
<franchise>
  <id type="integer">125</id>
  <name>FBI</name>
  <external-id>FB</external-id>
  <tags>Action,Drama</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/franchises/125"/>
  <link rel="brands" href="https://movida.bebanjo.net/api/franchises/125/brands"/>
  <link rel="titles" href="https://movida.bebanjo.net/api/franchises/125/titles"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/franchises/125/metadata"/>
  <link rel="images" href="https://movida.bebanjo.net/api/franchises/125/images"/>
  <link rel="licensor" href="https://movida.bebanjo.net/api/licensors/354"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/franchises/125/clips"/>
  <link rel="creator" href="https://movida.bebanjo.net/api/users/38"/>
</franchise>

{
  "resource_type": "franchise",
  "id": 125,
  "name": "FBI",
  "external_id": "FB",
  "tags": "Action,Drama",
  "acl_hash": "<view@everyone> <edit@team#141> <contribute@user#38>",
  "self_link": "https://movida.bebanjo.net/api/franchises/125",
  "brands_link": "https://movida.bebanjo.net/api/franchises/125/brands",
  "titles_link": "https://movida.bebanjo.net/api/franchises/125/titles",
  "metadata_link": "https://movida.bebanjo.net/api/franchises/125/metadata",
  "images_link": "https://movida.bebanjo.net/api/franchises/125/images",
  "licensor_link": "https://movida.bebanjo.net/api/licensors/354",
  "clips_link": "https://movida.bebanjo.net/api/franchises/125/clips",
  "creator_link": "https://movida.bebanjo.net/api/users/38"
}

Deleting a franchise

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

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

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

Note: Deleting a franchise won’t delete its contents in cascade. Those contents will keep existing but they won’t belong to any franchise.