Movida Resource: Image

Introduction

The Image resource represents all of the images associated to a title or title group, like posters, box covers, thumbnails, etc.

We're going to explain how to manipulate images associated with a title but you can do the same with images associated with title groups

In Movida land, an image looks like this:

<?xml version='1.0' encoding='utf-8' ?>
<image>
  <id type="integer">1</id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding>jpeg</encoding> <!-- Valid values: tif, tiff, gif, jpeg, jpg, png, pdf -->
  <aspect-ratio>4/3</aspect-ratio> <!-- Valid format: two numbers separated by : or / --> 
  <type>Poster</type>
  <file-name>movie.jpg</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1238791dhskajhfskajsfh</file-md5>
  <link href="https://movida.example.com/api/images/1" rel="self"/>
  <link href="http://wadus.com/movie.jpg" rel="file"/>
  <link href="https://movida.example.com/api/titles/45606" rel="content"/>
  <link href="https://movida.example.com/api/images/1/target_platforms" rel="target_platforms"/>
</image>

GET a List of all images of a title

Images are accessed via a Title. Refer to the Movida Resource: Title page to find out how to access a Title. Inside a Title, one of the related link nodes is the images node, identified by the rel attribute. Like here:

<?xml version='1.0' encoding='utf-8' ?>
<title>
  <!-- ... -->
  <link href="http://movida.example.com/api/titles/45606/images" rel="images"/>
  <!-- ... -->
</title>

If we follow that link we can fetch the list of all images for that title.

$ curl --digest -u robot_user:password https://movida.example.com/api/titles/45606/images

<?xml version="1.0" encoding="UTF-8"?>
<images type="array">
  <image>
    <id type="integer">1</id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>jpeg</encoding>
    <aspect-ratio>4/3</aspect-ratio>
    <type>Poster</type>
    <file-name>movie.jpg</file-name>
    <file-size type="integer">2345569434</file-size>
    <file-md5>1238791dhskajhfskajsfh</file-md5>
    <link href="https://movida.example.com/api/images/1" rel="self"/>
    <link href="http://wadus.com/movie.jpg" rel="file"/>
    <link href="https://movida.example.com/api/titles/45606" rel="content"/>
    <link href="https://movida.example.com/api/images/1/target_platforms" rel="target_platforms"/>
  </image>
  <image>
    <id type="integer">7</id>
    <width type="integer">1280</width>
    <height type="integer">720</height>
    <encoding>jpeg</encoding>
    <aspect-ratio>3/4</aspect-ratio>
    <type>BoxCover</type>
    <file-name>dvd_cover.jpg</file-name>
    <file-size type="integer">234556943</file-size>
    <file-md5>1238791dhskajhfskajsft</file-md5>
    <link href="https://staging-movida.bebanjo.net/api/images/7" rel="self"/>
    <link href="http://wadus.com/dvd_cover.jpg" rel="file"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/45606" rel="content"/>
    <link href="https://movida.example.com/api/images/7/target_platforms" rel="target_platforms"/>
  </image>
</images>

Creating images for a title

To create images, you just need to POST a proper XML image representation (similar to the ones you get when fetching an image) to the images URL of a title. That URL can be found in a link which 'rel' attribute equals 'images'. The only mandatory attribute is the encoding the rest are optional.

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

$ cat image.xml 
<image>
  <encoding>jpeg</encoding>
</image>

$ curl -u robot_user:password --digest -H "Content-Type: application/xml" -X POST -d @image.xml "http://movida.example.com/api/titles/45606/images"

Movida will return the full XML of the image just created:

<?xml version="1.0" encoding="UTF-8"?>
<image>
  <id type="integer">99</id>
  <width nil="true"></width>
  <height nil="true"></height>
  <encoding>jpeg</encoding>
  <aspect-ratio nil="true"></aspect-ratio>   
  <type nil="true"></type>
  <file-name nil="true"></file-name>
  <file-size nil="true"></file-size>
  <file-md5 nil="true"></file-md5>
  <link href="https://movida.example.com/api/images/1" rel="self"/>
  <link href="" rel="file"/>
  <link href="https://movida.example.com/api/titles/45606" rel="content"/>
  <link href="https://movida.example.com/api/images/1/target_platforms" rel="target_platforms"/>
</image>

Updating images of a title

You can update images issuing a PUT request to the URL of a given image, as the following example illustrates. This example only updates the image’s type, name, URL and dimensions.

$ cat image.xml 
<image>
  <width type="integer">1280</width>
  <height type="integer">720</width>
  <type>Thumbnail</type>
  <link href="http://wadus.com/movie.jpg" rel="file"/>
  <file-name>movie.jpg</file-name>
</image>

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

$ curl -u robot_user:password --digest -H "Content-Type: application/xml" -X PUT -d @image.xml "http://movida.example.com/api/images/1"

The PUT request would return the updated XML of the image:

<image>
  <id type="integer">1</id>
  <width type="integer">1280</width>
  <height type="integer">720</height>
  <encoding>jpeg</encoding>
  <aspect-ratio>4/3</aspect-ratio>
  <type>Thumbnail</type>
  <file-name>movie.jpg</file-name>
  <file-size nil="true"></file-size>
  <file-md5 nil="true"></file-md5>  
  <link href="https://movida.example.com/api/images/1" rel="self"/>
  <link href="http://wadus.com/movie.jpg" rel="file"/>
  <link href="https://movida.example.com/api/titles/45606" rel="content"/>
  <link href="https://movida.example.com/api/images/1/target_platforms" rel="target_platforms"/>
</image>

DELETE an image of a title

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

$ curl -u robot_user:password --digest -H "Content-Type: application/xml" -X DELETE "http://movida.example.com/api/images/1"

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