Movida Resource: Granted Requirement

Note: We have new docs! Please make your changes there bebanjo/docs

Introduction

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 Movida, a Granted Requirement will look like this:

<granted-requirement>
  <id type="integer">1</id>
  <link rel="self" href="https://movida.example.com/api/granted_requirements/1"/>
  <link rel="requirement" href="http://movida.example.com/api/requirements/3"/>
</granted-requirement>

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. Movida Resource: Blackout page to find out how to access a Blackout and Movida Resource: Right page 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="http://movida.example.com/api/blackouts/13/granted_requirements"/>
  <!-- ... -->
</blackout>

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

$ curl --digest -u robot_user:password http://movida.example.com/api/blackouts/13/granted_requirements

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

Example for a Right:

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

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

$ curl --digest -u robot_user:password http://movida.example.com/api/rights/13/granted_requirements

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

Creating a granted requirement for a blackout or right

To create a new granted requirement, you just need to POST a proper XML 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 
<granted_requirement>
  <link rel="requirement" href="http://movida.example.com/api/requirements/3"/>
</granted_requirement>

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

Movida will return the full XML 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.example.com/api/granted_requirements/10"/>
  <link rel="requirement" href="http://movida.example.com/api/requirements/3"/>
</granted_requirement>

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
<granted_requirement>
  <link rel="requirement" href="http://movida.example.com/api/requirements/4"/>
</granted_requirement>

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

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

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

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

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 -u robot_user:password --digest -H "Content-Type: application/xml" -X DELETE "https://movida.example.com/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.

Provide feedback

Saved searches