Developers

How can we help you?

Granted requirement

The granted requirement resource is used to specify the platform requirements a given blackout or right applies to. A given blackout or right will affect to those platforms having all the requirements specified in the granted requirements of the blackout/right.

In Mediagenix On-Demand, a granted requirement will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<granted-requirement>
  <id type="integer">1</id>
  <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/1"/>
  <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/3"/>
</granted-requirement>

{
  "resource_type": "granted_requirement",
  "id": 1,
  "self_link": "https://movida.bebanjo.net/api/granted_requirements/1",
  "requirement_link": "https://movida.bebanjo.net/api/requirements/3"
}

Listing all granted requirements of a blackout or right

Granted requirements are accessed via the blackout or right they belong to. Refer to the corresponding resource page, i.e. check the blackout resource to find out how to access a blackout and the right resource to find out how to access a right.

Inside a blackout or a right, one of the related link nodes is the granted_requirements node, identified by the rel attribute.

Example for a blackout:

<?xml version='1.0' encoding='utf-8' ?>
<blackout>
  <!-- ... -->
  <link rel="granted_requirements" href="https://movida.bebanjo.net/api/blackouts/13/granted_requirements"/>
  <!-- ... -->
</blackout>

{
  "resource_type": "blackout",
  // ...
  "granted_requirements_link": "https://movida.bebanjo.net/api/blackouts/13/granted_requirements",
  // ...
}

If we follow that link we can fetch the list of all granted requirements for that blackout.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/blackouts/13/granted_requirements

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

<granted_requirements type="array">
  <granted_requirement>
    <id type="integer">10</id>
    <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/10"/>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/3"/>
  </granted_requirement>
  <granted_requirement>
    <id type="integer">11</id>
    <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/11"/>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/2"/>
  </granted_requirement>
</granted_requirements>

{
  "entries": [
    {
      "resource_type": "granted_requirement",
      "id": 8656749,
      "self_link": "https://movida.bebanjo.net/api/granted_requirements/10",
      "requirement_link": "https://movida.bebanjo.net/api/requirements/3"
    },
    {
      "resource_type": "granted_requirement",
      "id": 8656752,
      "self_link": "https://movida.bebanjo.net/api/granted_requirements/11",
      "requirement_link": "https://movida.bebanjo.net/api/requirements/2"
    }
  ]
}

Example for a right:

<?xml version='1.0' encoding='utf-8' ?>
<right>
  <!-- ... -->
  <link rel="granted_requirements" href="https://movida.bebanjo.net/api/rights/13/granted_requirements"/>
  <!-- ... -->
</right>

{
  "resource_type": "right",
  // ...
  "granted_requirements_link": "https://movida.bebanjo.net/api/rights/13/granted_requirements",
  // ...
}

If we follow that link we can fetch the list of all granted requirements for that right.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/rights/13/granted_requirements

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

<granted_requirements type="array">
  <granted_requirement>
    <id type="integer">10</id>
    <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/10"/>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/3"/>
  </granted_requirement>
  <granted_requirement>
    <id type="integer">11</id>
    <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/11"/>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/2"/>
  </granted_requirement>
</granted_requirements>

{
  "entries": [
    {
      "resource_type": "granted_requirement",
      "id": 10,
      "self_link": "https://movida.bebanjo.net/api/granted_requirements/10",
      "requirement_link": "https://movida.bebanjo.net/api/requirements/3"
    },
    {
      "resource_type": "granted_requirement",
      "id": 11,
      "self_link": "https://movida.bebanjo.net/api/granted_requirements/11",
      "requirement_link": "https://movida.bebanjo.net/api/requirements/2"
    }
  ]
}

Creating a granted requirement for a blackout or right

To create a new granted requirement, you just need to POST a proper granted requirement representation to the granted requirements URL of the resource. That URL can be found in a link which rel attribute equals granted_requirements. The only information required to include in the payload is a link to a requirement.

For example, this POST would create a granted requirement (we’ll use curl’s @ option, which reads data to be posted from a file):

$ cat granted_requirement.xml

$ cat granted_requirement.json

<granted_requirement>
  <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/3"/>
</granted_requirement>

{
  "requirement_link": "https://movida.bebanjo.net/api/requirements/3"
}

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<granted_requirement>
  <id type="integer">10</id>
  <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/10"/>
  <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/3"/>
</granted_requirement>

{
  "resource_type": "granted_requirement",
  "id": 10,
  "self_link": "https://movida.bebanjo.net/api/granted_requirements/10",
  "requirement_link": "https://movida.bebanjo.net/api/requirements/3"
}

However, you’re not limited to creating one granted_requirement at a time. You can easily create multiple granted requirements with only one API request (and that is, indeed, the preferred way to do it) instead of making multiple consecutive requests.

For that, you’ll need to wrap your granted_requirement entities with a granted_requirements node in the XML/JSON payload. For example, this payload will create 3 granted requirements for this blackout:

$ cat granted_requirements_batch.xml

$ cat granted_requirements_batch.json

<granted-requirements type="array">
  <granted_requirement>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/3"/>
  </granted_requirement>
  <granted_requirement>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/4"/>
  </granted_requirement>
  <granted_requirement>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/5"/>
  </granted_requirement>
</granted-requirements>

{
  "granted_requirements": [
    {
      "requirement_link": "https://movida.bebanjo.net/api/requirements/3"
    },
    {
      "requirement_link": "https://movida.bebanjo.net/api/requirements/4"
    },
    {
      "requirement_link": "https://movida.bebanjo.net/api/requirements/5"
    }
  ]
}

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

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

The response will contain the XML/JSON representation of the created entities:

<?xml version="1.0" encoding="UTF-8"?>
<granted-requirements type="array">
  <granted_requirement>
    <id type="integer">10</id>
    <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/10"/>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/3"/>
  </granted_requirement>
  <granted_requirement>
    <id type="integer">11</id>
    <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/11"/>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/4"/>
  </granted_requirement>
  <granted_requirement>
    <id type="integer">12</id>
    <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/12"/>
    <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/5"/>
  </granted_requirement>
</granted-requirements>

{
  "entries": [
    {
      "resource_type": "granted_requirement",
      "id": 10,
      "self_link": "https://movida.bebanjo.net/api/granted_requirements/10",
      "requirement_link": "https://movida.bebanjo.net/api/requirements/3"
    },
    {
      "resource_type": "granted_requirement",
      "id": 11,
      "self_link": "https://movida.bebanjo.net/api/granted_requirements/11",
      "requirement_link": "https://movida.bebanjo.net/api/requirements/4"
    },
    {
      "resource_type": "granted_requirement",
      "id": 12,
      "self_link": "https://movida.bebanjo.net/api/granted_requirements/12",
      "requirement_link": "https://movida.bebanjo.net/api/requirements/5"
    }
  ]
}

Note:

The request will either create all of the granted requirements, if all is correct, or none, if there’s any error. Note that all the requirements must previously exist.

You just need to include the granted requirements that need to be created in the payload, i.e. you don’t need to include the already existing ones. The granted requirements will be added on top of the existing ones, which will be kept.

If you include a granted requirement that already exists in the payload, it’ll be ignored: it won’t be duplicated and it won’t raise any error.

Currently, you can create up to 50 granted requirements in this way. If your payload includes more than 50 granted requirements, you’ll receive a 422 HTTP error response.

Updating a granted requirement

You can update granted requirement using a PUT request to the URL of a given granted requirement, as the following example illustrates.

$ cat granted_requirement.xml

$ cat granted_requirement.json

<granted_requirement>
  <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/4"/>
</granted_requirement>

{
  "requirement_link": "https://movida.bebanjo.net/api/requirements/4"
}

Now we send the XML/JSON as the body of a PUT request to the granted_requirements’s URL

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

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

The PUT request would return the updated XML/JSON of the granted requirement:

<granted_requirement>
  <id type="integer">10</id>
  <link rel="self" href="https://movida.bebanjo.net/api/granted_requirements/10"/>
  <link rel="requirement" href="https://movida.bebanjo.net/api/requirements/4"/>
</granted_requirement>

{
  "resource_type": "granted_requirement",
  "id": 10,
  "self_link": "https://movida.bebanjo.net/api/granted_requirements/10",
  "requirement_link": "https://movida.bebanjo.net/api/requirements/4"
}

Deleting a granted requirement

The following example shows how to destroy a particular granted requirement. Only a DELETE HTTP request to its URL is required:

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

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

The DELETE request doesn’t return anything, as that granted requirement is now gone.

Deleting a granted requirement doesn’t delete the grantor (blackout or right) nor the requirement.