Skip to content

Movida Resource: Image

Jump to bottom Edit New page
Fernando Blat edited this page Jun 12, 2014 · 26 revisions

Introduction

The Image resource represents all of the images associated to a title, a title group or a brand, 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 and brands.

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

  • id (mandatory): Movida internal identifier of the image. It shouldn't be provided in the creation of the resource, because Movida will assign that value.
  • encoding (mandatory): encoding of the image. Valid values are: tif, tiff, gif, jpeg, jpg, png, pdf.
  • width (optional): width size of the image
  • height (optional): height size of the image
  • aspect-ratio (optional): aspect ratio of the image. The separator must be ':' or '/'
  • type (optional): the type of the image. There isn´t a closed list of values
  • file-name (optional): the name of the file
  • file-size (optional): the size of the file
  • file-md5 (optional): the MD5 of the file
  • link to the file (optional): the URL to the image file in the cloud storage

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

Creating images providing an external URL

There´s another way to create images, by providing an external URL to an existing image in the file-url parameter. See the above payload as an example:

$ cat image.xml
<image>
  <encoding>jpg</encoding>
  <file-url>https://external-domain.com/836f80e394fbe24348ace81.jpg</file-url>
</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>jpg</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/99" rel="self"/>
  <link href="https://external-domain.com/836f80e394fbe24348ace81.jpg" rel="file"/>
  <link href="https://movida.example.com/api/titles/45606" rel="content"/>
  <link href="https://movida.example.com/api/images/99/target_platforms" rel="target_platforms"/>
</image>

Asynchronously, Movida will be retrieve the image and its attributes, such as dimensions or MD5 and will update the existing resource with these information (some of the values provided in the creation will be updated).

Eventually, when it finishes most of the attributes of the image will have been overwritten by Movida, with the values corresponding to the provided image:

$ curl --digest -u robot_user:password https://movida.example.com/api/images/99
<?xml version="1.0" encoding="UTF-8"?>
<image>
  <id type="integer">99</id>
  <width type="integer">800</width>
  <height type="integer">600</height>
  <encoding>jpg</encoding>
  <aspect-ratio>4/3</aspect-ratio>
  <type></type>
  <file-name>836f80e394fbe24348ace81.jpg</file-name>
  <file-size type="integer">2345569434</file-size>
  <file-md5>1238791dhskajhfskajsfh</file-md5>
  <link href="https://movida.example.com/api/images/99" rel="self"/>
  <link href="https://movida-cloud-image-storage.com/images/343421421-as21232.jpg" rel="file"/>
  <link href="https://movida.example.com/api/titles/45606" rel="content"/>
  <link href="https://movida.example.com/api/images/99/target_platforms" rel="target_platforms"/>
</image>

The only way to check if an image has been fetched and its attributes have been updated is by comparing the value of the attribute link[rel=file] with the original value provided in the creation request.

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>

Notice that the attribute link[rel=file] can´t be updated.

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.

Deleting an image won´t have any side-effect on linked resources such as the title or the series.

Add a custom footer
Add a custom sidebar
Clone this wiki locally