Skip to content

Developers

How can we help you?

← Go back

Contributor

Note: Only Mediagenix On-Demand accounts with this feature enabled will expose this API.

The contributor resource represents any individual that takes part in the production of a piece of audiovisual content. E.g. actors, directors, producers, camera staff, etc.

It can be linked to a title, title group or brand via a credit resource.

This is how a Contributor resource looks in the API:

<?xml version="1.0" encoding="UTF-8"?>
<contributor>
  <id type="integer">1</id>
  <first-name>Jackie</first-name>
  <last-name>Chan</last-name>
  <external-id>SAMPLE_ID</external-id>
  <biography>Let's keep this short</biography>
  <tags>actors,trending,martial</tags>
  <link rel="self" href="https://movida.bebanjo.net/api/contributors/1"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/contributors/1/credits"/>
  <link rel="images" href="https://movida.bebanjo.net/api/contributors/1/images"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/contributors/1/metadata"/>
</contributor>

{
  "resource_type": "contributor",
  "id": 1,
  "first_name": "Jackie",
  "last_name": "Chan",
  "external_id": "SAMPLE_ID",
  "biography": "Let's keep this short",
  "tags": "actors,trending,martial",
  "self_link": "https://movida.bebanjo.net/api/contributors/1",
  "credits_link": "https://movida.bebanjo.net/api/contributors/1/credits",
  "images_link": "https://movida.bebanjo.net/api/contributors/1/images",
  "metadata_link": "https://movida.bebanjo.net/api/contributors/1/metadata"
}

Valid attributes

  • id (required): Mediagenix On-Demand’s internal identifier for the contributor. It must not be supplied in the creation of the contributor, it will be set automatically.

  • first-name (required): the first name of the contributor

  • last-name (optional): the last name of the contributor.

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

  • biography (optional): a brief account of this contributor’s career.

  • tags (optional): a list of tags, separated by commas.

Getting a list of contributors

To return a (paginated) list of all the contributors in the account, you can send a GET request like the following:

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

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

<?xml version="1.0" encoding="UTF-8"?>
<contributors type="array">
  <total-entries>174</total-entries>
  <link rel="next" href="https://movida.bebanjo.net/api/contributors?page=2"/>
  <contributor>
    <id type="integer">1</id>
    <first-name>Jackie</first-name>
    <last-name>Chan</last-name>
    <external-id>SAMPLE_ID</external-id>
    <biography>Let's keep this short</biography>
    <tags>actors,trending,martial</tags>
    <link rel="self" href="https://movida.bebanjo.net/api/contributors/1"/>
    <link rel="credits" href="https://movida.bebanjo.net/api/contributors/1/credits"/>
    <link rel="images" href="https://movida.bebanjo.net/api/contributors/1/images"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/contributors/1/metadata"/>
  </contributor>
  <contributor>
    <id type="integer">2</id>
    <first-name>Stacie</first-name>
    <last-name>Chan</last-name>
    <external-id nil="true"/>
    <biography nil="true"/>
    <tags></tags>
    <link rel="self" href="https://movida.bebanjo.net/api/contributors/2"/>
    <link rel="credits" href="https://movida.bebanjo.net/api/contributors/2/credits"/>
    <link rel="images" href="https://movida.bebanjo.net/api/contributors/2/images"/>
    <link rel="metadata" href="https://movida.bebanjo.net/api/contributors/2/metadata"/>
  </contributor>
  <!-- .... -->
</contributors>

{
  "total_entries": 174,
  "next_link": "https://movida.bebanjo.net/api/contributors?page=2",
  "entries": [
    {
      "resource_type": "contributor",
      "id": 1,
      "first_name": "Jackie",
      "last_name": "Chan",
      "external_id": "SAMPLE_ID",
      "biography": "Let's keep this short",
      "tags": "actors,trending,martial",
      "self_link": "https://movida.bebanjo.net/api/contributors/1",
      "credits_link": "https://movida.bebanjo.net/api/contributors/1/credits",
      "images_link": "https://movida.bebanjo.net/api/contributors/1/images",
      "metadata_link": "https://movida.bebanjo.net/api/contributors/1/metadata"
    },
    {
      "resource_type": "contributor",
      "id": 2,
      "first_name": "Stacie",
      "last_name": "Chan",
      "external_id": "1033",
      "biography": null,
      "tags": "",
      "self_link": "https://movida.bebanjo.net/api/contributors/2",
      "credits_link": "https://movida.bebanjo.net/api/contributors/2/credits",
      "images_link": "https://movida.bebanjo.net/api/contributors/2/images",
      "metadata_link": "https://movida.bebanjo.net/api/contributors/2/metadata"
    },
    // ...
  ]
}

Note that this is a paginated resource. By default, only 50 contributors 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.

Valid attributes

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

  • external_id: It will return only the contributor with that specific external id (if any).

  • full_name: It will return only the set of contributors whose name matches the query (if any).

  • per_page: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50.

Getting a specific contributor

This operation allows you to recover information about one specific contributor.

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

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

<?xml version="1.0" encoding="UTF-8"?>
<contributor>
  <id type="integer">1</id>
  <first-name>Jackie</first-name>
  <last-name>Chan</last-name>
  <external-id>SAMPLE_ID</external-id>
  <biography>Let's keep this short</biography>
  <tags>actors, trending, martial</tags>
  <link rel="self" href="https://movida.bebanjo.net/api/contributors/1"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/contributors/1/credits"/>
  <link rel="images" href="https://movida.bebanjo.net/api/contributors/1/images"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/contributors/1/metadata"/>
</contributor>

{
  "resource_type": "contributor",
  "id": 14820,
  "first_name": "Tianyuan",
  "last_name": "Huang",
  "external_id": null,
  "biography": null,
  "tags": "",
  "self_link": "https://movida.bebanjo.net/api/contributors/14820",
  "credits_link": "https://movida.bebanjo.net/api/contributors/14820/credits",
  "images_link": "https://movida.bebanjo.net/api/contributors/14820/images",
  "metadata_link": "https://movida.bebanjo.net/api/contributors/14820/metadata"
}

Creating a new contributor

To create a contributor, you just need to POST a proper representation of a contributor, similar to what you get when fetching one, to the proper endpoint.

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

$ cat contributor.xml

$ cat contributor.json

<?xml version="1.0" encoding="UTF-8"?>
<contributor>
  <first-name>Clint</first-name>
  <last-name>Eastwood</last-name>
  <external-id>clint_ID</external-id>
  <biography>Actor, director, what a superstar</biography>
  <tags>best actors, best directors</tags>
</contributor>

{
  "first_name": "Clint",
  "last_name": "Eastwood",
  "external_id": "clint_ID",
  "biography": "Actor, director, what a superstar",
  "tags": "best actors, best directors"
}

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

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

Mediagenix On-Demand will return the full XML/JSON of the contributor just created:

<?xml version="1.0" encoding="UTF-8"?>
<contributor>
  <id type="integer">3</id>
  <first-name>Clint</first-name>
  <last-name>Eastwood</last-name>
  <external-id>clint_ID</external-id>
  <biography>Actor, director, what a superstar</biography>
  <tags>best actors, best directors</tags>
  <link rel="self" href="https://movida.bebanjo.net/api/contributors/3"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/contributors/3/credits"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/contributors/3/metadata"/>
  <link rel="images" href="https://movida.bebanjo.net/api/contributors/3/images"/>
</contributor>

{
  "resource_type": "contributor",
  "id": 3,
  "first_name": "Clint",
  "last_name": "Eastwood",
  "external_id": "clint_ID",
  "biography": "Actor, director, what a superstar",
  "tags": "best actors,best directors",
  "self_link": "https://movida.bebanjo.net/api/contributors/3",
  "credits_link": "https://movida.bebanjo.net/api/contributors/3/credits",
  "images_link": "https://movida.bebanjo.net/api/contributors/3/images",
  "metadata_link": "https://movida.bebanjo.net/api/contributors/3/metadata"
}

Dealing with names

If instead of the first-name and last-name you just have one single piece, the full name, don’t worry, we have a solution for you! Just send a full-name node, and we’ll do the magic behind the scenes for you.

$ cat contributor_with_full_name.xml

$ cat contributor_with_full_name.json

<?xml version="1.0" encoding="UTF-8"?>
<contributor>
  <full-name>Clint Eastwood</full-name>
</contributor>

{
  "full_name": "Clint Eastwood"
}

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

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

As you can see, we try to do our best to separate the full name into pieces:

<?xml version="1.0" encoding="UTF-8"?>
<contributor>
  ...
  <first-name>Clint</first-name>
  <last-name>Eastwood</last-name>
  ...
</contributor>

{
  "resource_type": "contributor",
  // ...
  "first_name": "Clint",
  "last_name": "Eastwood",
  // ...
}

Updating a contributor

As our introduction to REST APIs guide page suggests, you can update a contributor just by issuing a PUT request to each contributor URI. You only need to include those attributes that you wish to update:

$ cat contributor_update.xml

$ cat contributor_update.json

<contributor>
  <biography>
    Perhaps the icon of macho movie stars, Clint Eastwood has become a standard in international cinema...
  </biography>
</contributor>

{
  "biography": "Perhaps the icon of macho movie stars, Clint Eastwood has become a standard in international cinema..."
}

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

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

As always, Mediagenix On-Demand will return the full XML/JSON of the resource just updated:

<?xml version="1.0" encoding="UTF-8"?>
<contributor>
  <id type="integer">3</id>
  <first-name>Clint</first-name>
  <last-name>Eastwood</last-name>
  <external-id>clint_ID</external-id>
  <biography>
    Perhaps the icon of macho movie stars, Clint Eastwood has become a standard in international cinema...
  </biography>
  <tags>best actors, best directors</tags>
  <link rel="self" href="https://movida.bebanjo.net/api/contributors/3"/>
  <link rel="credits" href="https://movida.bebanjo.net/api/contributors/3/credits"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/contributors/3/metadata"/>
  <link rel="images" href="https://movida.bebanjo.net/api/contributors/3/images"/>
</contributor>

{
  "resource_type": "contributor",
  "id": 3,
  "first_name": "Clint",
  "last_name": "Eastwood",
  "external_id": "clint_ID",
  "biography": "Perhaps the icon of macho movie stars, Clint Eastwood has become a standard in international cinema...",
  "tags": "best actors, best directors",
  "self_link": "https://movida.bebanjo.net/api/contributors/3",
  "credits_link": "https://movida.bebanjo.net/api/contributors/3/credits",
  "images_link": "https://movida.bebanjo.net/api/contributors/3/images",
  "metadata_link": "https://movida.bebanjo.net/api/contributors/3/metadata"
}

Deleting a contributor

You can also delete a contributor by sending a DELETE request to each contributor URI:

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

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

Take into account that all the credits of the contributor, if any, will be deleted too.

Metadata and images

A contributor can have its own metadata and images. Which behaves exactly as in other resources like for instance titles, title group, or brands.