Movida Resource: Granted Requirement

Introduction

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

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 the granted requirements of a blackout

Granted Requirements are accessed via the blackout they belong to. Refer to the corresponding resource page, i.e. Movida Resource: Blackout page to find out how to access a Blackout. Inside a Blackout, one of the related link nodes is the granted_requirements node, identified by the rel attribute. Like here:

<?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>

Creating granted requirement for a blackout

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_platforms'. The only information required to include in the payload is a link to a platform.

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 target_platform’s URL

$ curl -u robot_user:password --digest -H "Content-Type: application/xml" -X PUT -d @target_platform.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 blackout nor the requirement.