Developers

How can we help you?

Credit

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

A credit resource represents the link between a contributor and one title, title group or brand. Basically, it acknowledges a contributor’s role in a piece of content.

Have in mind that the same contributor can be credited more than once for the same creditable (title, title group or brand), since the same person may have a role as actor but also as director or producer.

This is how a credit resource looks like in the API:

<?xml version="1.0" encoding="UTF-8"?>
<credit>
  <id type="integer">1</id>
  <credit-role-name>Actor</credit-role-name>
  <character-name>Walt Kowalski</character-name>
  <position type="integer">1</position>
  <link rel="self" href="https://movida.bebanjo.net/api/credits/1"/>
  <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/3"/>
  <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/1"/>
  <link rel="creditable" href="https://movida.bebanjo.net/api/titles/1"/>
</credit>

{
  "resource_type": "credit",
  "id": 1,
  "credit_role_name": "Actor",
  "character_name": "Walt Kowalski",
  "position": 1,
  "self_link": "https://movida.bebanjo.net/api/credits/1",
  "contributor_link": "https://movida.bebanjo.net/api/contributors/3",
  "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/1",
  "creditable_link": "https://movida.bebanjo.net/api/titles/1"
}

Please, refer to the contributors and credit roles wiki pages for more information.

Valid attributes

id (required): Mediagenix On-Demand’s internal identifier for a credit. It must not be supplied in the creation of the credit, it will be set automatically.
credit-role-name (read-only): the name of the role the contributor is being credited for. This is defined as a read-only attribute here just for convenience. Please, follow the credit_role link for detailed information on the role.
character-name (optional): the character name for this contributor. Depending on the role, you may want to set a character name for this credit.
position (optional): the position of this credit within the list of credits of a piece of content. The value, if provided, must be greater than zero. And if not provided, it will be automatically assigned to the next available position.

Getting the list of credits of a piece of content

To return a (paginated) list of the credits for a title, title group or brand, you can just follow the “credits” link in any of these resources. For titles, for example, you could issue a GET request like the following:

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

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

<?xml version="1.0" encoding="UTF-8"?>
<credits type="array">
  <credit>
    <id type="integer">1</id>
    <credit-role-name>Actor</credit-role-name>
    <character-name>Walt Kowalski</character-name>
    <position type="integer">1</position>
    <link rel="self" href="https://movida.bebanjo.net/api/credits/1"/>
    <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/3"/>
    <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/1"/>
    <link rel="creditable" href="https://movida.bebanjo.net/api/titles/1"/>
  </credit>
  <credit>
    <id type="integer">2</id>
    <credit-role-name>director</credit-role-name>
    <character-name></character-name>
    <position type="integer">2</position>
    <link rel="self" href="https://movida.bebanjo.net/api/credits/12"/>
    <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/4"/>
    <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/2"/>
    <link rel="creditable" href="https://movida.bebanjo.net/api/titles/1"/>
  </credit>
</credits>

{
  "entries": [
    {
      "resource_type": "credit",
      "id": 1,
      "credit_role_name": "Actor",
      "character_name": "Walt Kowalski",
      "position": 1,
      "self_link": "https://movida.bebanjo.net/api/credits/1",
      "contributor_link": "https://movida.bebanjo.net/api/contributors/3",
      "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/1",
      "creditable_link": "https://movida.bebanjo.net/api/titles/1"
    },
    {
      "resource_type": "credit",
      "id": 2,
      "credit_role_name": "Director",
      "character_name": "",
      "position": 2,
      "self_link": "https://movida.bebanjo.net/api/credits/2",
      "contributor_link": "https://movida.bebanjo.net/api/contributors/4",
      "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/2",
      "creditable_link": "https://movida.bebanjo.net/api/titles/1"
    }
  ]
}

In this example you can see how the same contributor, Clint Eastwood, is being credited twice in the same title, with two different roles.

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

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

Getting the list of credits of a contributor

If instead of getting the list of credits of a piece of content you want to get all the credits for a specific contributor, you can follow the same approach: visit the “credits” link in any of them or issue a GET request like the following one, for Clint Eastwood:

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

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

That will return a (paginated) list of all his credits:

<?xml version="1.0" encoding="UTF-8"?>
<credits type="array">
  <credit>
    <id type="integer">1</id>
    <credit-role-name>Actor</credit-role-name>
    <character-name>Walt Kowalski</character-name>
    <position type="integer">1</position>
    <link rel="self" href="https://movida.bebanjo.net/api/credits/1"/>
    <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/3"/>
    <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/18"/>
    <link rel="creditable" href="https://movida.bebanjo.net/api/titles/1"/>
  </credit>
  <credit>
    <id type="integer">12</id>
    <credit-role-name>Actor</credit-role-name>
    <character-name>Pedro Henrique</character-name>
    <position type="integer">9</position>
    <link rel="self" href="https://movida.bebanjo.net/api/credits/12"/>
    <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/3"/>
    <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/18"/>
    <link rel="creditable" href="https://movida.bebanjo.net/api/titles/23"/>
  </credit>
</credits>

{
  "entries": [
    {
      "resource_type": "credit",
      "id": 1,
      "credit_role_name": "Actor",
      "character_name": "Walt Kowalski",
      "position": 1,
      "self_link": "https://movida.bebanjo.net/api/credits/1",
      "contributor_link": "https://movida.bebanjo.net/api/contributors/3",
      "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/18",
      "creditable_link": "https://movida.bebanjo.net/api/titles/1"
    },
    {
      "resource_type": "credit",
      "id": 12,
      "credit_role_name": "Actor",
      "character_name": "Pedro Henrique",
      "position": 9,
      "self_link": "https://movida.bebanjo.net/api/credits/12",
      "contributor_link": "https://movida.bebanjo.net/api/contributors/3",
      "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/18",
      "creditable_link": "https://movida.bebanjo.net/api/titles/23"
    }
  ]
}

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

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

Getting a specific credit

This operation allows you to recover information about one specific credit:

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

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

<?xml version="1.0" encoding="UTF-8"?>
<credit>
  <id type="integer">1</id>
  <credit-role-name>Actor</credit-role-name>
  <character-name>Walt Kowalski</character-name>
  <position type="integer">1</position>
  <link rel="self" href="https://movida.bebanjo.net/api/credits/1"/>
  <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/3"/>
  <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/18"/>
  <link rel="creditable" href="https://movida.bebanjo.net/api/titles/1"/>
</credit>

{
  "resource_type": "credit",
  "id": 1,
  "credit_role_name": "Actor",
  "character_name": "Walt Kowalski",
  "position": 1,
  "self_link": "https://movida.bebanjo.net/api/credits/1",
  "contributor_link": "https://movida.bebanjo.net/api/contributors/3",
  "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/18",
  "creditable_link": "https://movida.bebanjo.net/api/titles/1"
}

Crediting a contributor in a piece of content

To credit an existing contributor you just have to POST a payload like the following to the credits link of any title, title group or brand. Let’s suppose we want to add the almighty Clint Eastwood as Harry in Dirty Harry (title with id 4 in our example):

$ cat new_credit_existing_contributor.xml

$ cat new_credit_existing_contributor.json

<?xml version="1.0" encoding="UTF-8"?>
<credit>
  <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/3" />
  <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/1" />
  <character-name>Harry</character-name>
  <position>1</position>
</credit>

{
  "contributor_link": "https://movida.bebanjo.net/api/contributors/3",
  "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/1",
  "character_name": "Harry",
  "position": 1
}

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

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

Mediagenix On-Demand will then return the full XML/JSON of our brand new credit, as usual:

<?xml version="1.0" encoding="UTF-8"?>
<credit>
  <id type="integer">3</id>
  <credit-role-name>Actor</credit-role-name>
  <character-name>Harry</character-name>
  <position type="integer">1</position>
  <link rel="self" href="https://movida.bebanjo.net/api/credits/3"/>
  <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/7"/>
  <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/18"/>
  <link rel="creditable" href="https://movida.bebanjo.net/api/titles/4"/>
</credit>

{
  "resource_type": "credit",
  "id": 3,
  "credit_role_name": "Actor",
  "character_name": "Harry",
  "position": 1,
  "self_link": "https://movida.bebanjo.net/api/credits/3",
  "contributor_link": "https://movida.bebanjo.net/api/contributors/7",
  "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/18",
  "creditable_link": "https://movida.bebanjo.net/api/titles/4"
}

Attempting to add a duplicate credit (matching an existing contributor, credit role and character name) will result in an error response:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Credit has already been taken</error>
</errors>

{
  "errors": [
    "Credit has already been taken"
  ]
}

Crediting a new contributor in a piece of content

Chances are that you want to credit someone that has not been created as a contributor yet. Good news: you can do it all in just one shot!

Let’s suppose here that we want to credit Gillian Anderson as Dana Scully —of course!— in our X-Files brand. Just POST a request with a payload like the following to the “credits” link of the brand:

$ cat new_credit_new_contributor.xml

$ cat new_credit_new_contributor.json

<?xml version="1.0" encoding="UTF-8"?>
<credit>
  <link rel="contributor">
    <contributor>
      <full-name>Gillian Anderson</full-name>
      <external-id>gillian-sample-ext-id</external-id>
    </contributor>
  </link>
  <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/1" />
  <character-name>Dana Scully</character-name>
  <position>1</position>
</credit>

{
  "link": {
    "rel": "contributor",
    "contributor": {
      "full_name": "Gillian Anderson",
      "external_id": "gillian-sample-ext-id"
    }
  },
  "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/1",
  "character_name": "Dana Scully",
  "position": 1
}

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

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

Mediagenix On-Demand will reply with the XML/JSON of the new credit:

<?xml version="1.0" encoding="UTF-8"?>
<credit>
  <id type="integer">4</id>
  <credit-role-name>actor</credit-role-name>
  <character-name>Dana Scully</character-name>
  <position type="integer">1</position>
  <link rel="self" href="https://movida.bebanjo.net/api/credits/4"/>
  <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/4"/>
  <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/1"/>
  <link rel="creditable" href="https://movida.bebanjo.net/api/brands/1"/>
</credit>

{
  "resource_type": "credit",
  "id": 4,
  "credit_role_name": "Actor",
  "character_name": "Dana Scully",
  "position": 1,
  "self_link": "https://movida.bebanjo.net/api/credits/4",
  "contributor_link": "https://movida.bebanjo.net/api/contributors/4",
  "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/1",
  "creditable_link": "https://movida.bebanjo.net/api/brands/1"
}

This would have created a new contributor and a new credit for it, all within the same request. As of this writing, only the contributor’s name and their external ID are supported when creating the contributor this way.

Updating a credit

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

$ cat credit_update.xml

$ cat credit_update.json

<credit>
  <character-name>Special Agent Dana Katherine Scully</character-name>
</credit>

{
  "character_name": "Special Agent Dana Katherine Scully"
}

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<credit>
  <id type="integer">4</id>
  <credit-role-name>actor</credit-role-name>
  <character-name>Special Agent Dana Katherine Scully</character-name>
  <position type="integer">1</position>
  <link rel="self" href="https://movida.bebanjo.net/api/credits/4"/>
  <link rel="contributor" href="https://movida.bebanjo.net/api/contributors/4"/>
  <link rel="credit_role" href="https://movida.bebanjo.net/api/credit_roles/1"/>
  <link rel="creditable" href="https://movida.bebanjo.net/api/brands/1"/>
</credit>

{
  "resource_type": "credit",
  "id": 4,
  "credit_role_name": "Actor",
  "character_name": "Special Agent Dana Katherine Scully",
  "position": 1,
  "self_link": "https://movida.bebanjo.net/api/credits/4",
  "contributor_link": "https://movida.bebanjo.net/api/contributors/4",
  "credit_role_link": "https://movida.bebanjo.net/api/credit_roles/1",
  "creditable_link": "https://movida.bebanjo.net/api/brands/1"
}

Deleting a credit

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

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

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