Skip to main content
Documentation & User Guides | Fotoware

Downloading asset renditions using the RESTful API

  1. Last updated
  2. Save as PDF
Applies to:FotoWare 8.0 Feature Release 10

 

 

Integrations and applications can download assets from a FotoWeb site using the FotoWeb RESTful API. The same download options are available as for interactive users. This means that

Downloading an asset requires the following steps:

  1. Obtain a rendition URL
  2. Create a rendition request
  3. Download the rendition

The first step is necessary because each asset can have multiple renditions. The second step is necessary because the server may need time to prepare the rendition (e.g., by applying a processing profile or metadata filtering to the original asset). When the rendition is ready, the client can download it from a temporary URL provided by the server.

Notes

  • The API only allows download of a single rendition of a single file per request. It is not possible to download multiple files as a ZIP file (as interactive users can do).
  • It is not possible to download XMP sidecar files. This means that when downloading a file of a type which does not support embedded XMP metadata (such as a PowerPoint presentation), then the downloaded file will not include any metadata. To export metadata of assets, the API can be used to get a JSON representation of the metadata. It is, however, not easy to convert this information into XMP format.

Authentication and Impersonation

Both guests and authenticated users can download assets. It is possible to download assets using the API as long as the guest user has download permission on these assets.

Different users may have access to different renditions (or no renditions at all). It is therefore recommended to perform all three steps of the download process with the same request user. For example, if the rendition request is made as the Guest user, then the rendition URL should be obtained as the Guest user, because otherwise, it is not guaranteed that Guest has access to this rendition, and the rendition request may fail.

When using server-to-server authentication, all configured renditions are available for all assets in all archives.

Renditions

The JSON representation of an asset contains a renditions list, which is a list of renditions that are available for download in the renditions parameter. It is up to the API client to choose which rendition to download. An interactive application may also present the rendition list to the user in a similar way as the FotoWeb download interface does and let the user select a rendition.

How renditions are configured

Renditions are configured in the FotoWeb Site Settings in the Operations Center, under Processing Profiles. Having made one or more processing profiles, you can collect these in a set, which can be applied to an archive, where the file can be delivered in one of three ways:
1) in its original form, 2) always processed with the processing profile the administrator has associated with the archive, or 3) based on the available processing profiles in the set that the admin has associated with the archive.

Each item in the rendition list has the following form:

{
  "display_name": "Original File",
  "description": "Original File",
  "width": 5472,
  "height": 3648,
  "href": "/fotoweb/archives/5000-Photos/Folder/image.jpg.info/__renditions/ORIGINAL",
  "default": true|false,
  "original": true|false
}

where

Parameter

Type

Description
display_name string Human-readable display name of the rendition
description string Human-readable detailed description of the rendition
width integer Width of the rendition in pixels (if applicable)
height integer Height of the rendition in pixels (if applicable)
href URL (string) Rendition URL
default boolean If true, this rendition is the default rendition that should be offered to users in a selection interface
original boolean If true, this rendition is the original asset file without any processing applied

Notes:

  • Clients can use the display_name attribute as a unique identifier of a specific rendition type. It is identical to the name of the processing profile that is applied to the asset, unless original is true, which means that no processing profile is applied.
  • It is not possible to make requests to the rendition URL. The rendition cannot be downloaded from this URL. The rendition URL only serves as an identifier of a specific rendition of a specific asset. The remainder of this article explains how to download assets using the API.

Rendition Requests

Rendition requests are made to the rendition request service using the rendition URL from the rendition list:

POST RENDITION_REQUEST_SERVICE_URL
Content-Type: application/vnd.fotoware.rendition-request+json
Accept: application/vnd.fotoware.rendition-response+json


{
  "href": "RENDITION_URL"
}

The server returns one of the following responses:

202 Accepted
Location: RENDITION_REQUEST_URL
Content-Type: application/vnd.fotoware.rendition-response+json
{
  href: "RENDITION_REQUEST_URL"
}

403 Forbidden

This means that the impersonated user (or guest) does not (or does not longer have) permission to download the rendition.

How to obtain the Rendition Request Service URL

The request URL (RENDITION_REQUEST_SERVICE_URL) is obtained from the API descriptor. It is provided both in the full API descriptor as well as in the public API descriptor in the services.rendition_requests attribute:

 {
  ...
  services: {
    ...
    rendition_requests: "RENDITION_REQUEST_SERVICE_URL",
    ...
  }
  ...
}

The href parameter in the request body must be the rendition URL obtained from the rendition list of the asset representation.

The response contains a temporary rendition request URL, RENDITION_REQUEST_URL, which the client can use to download the rendition when it is ready.

Polling and Downloading the Rendition

To download the rendition, the client makes the following request to the rendition request URL obtained in the previous step:

GET RENDITION_REQUEST_URL

If the rendition request URL is valid, the server returns one of the following responses:

202 Accepted

This response means that the rendition is not ready yet, and the client should retry the request after a short delay.

200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="image.jpg"

This response means that the rendition is ready. The binary rendition file is contained in the body of the response (as in a regular HTTP download response).

The Content-Type header is currently always application/octet-stream. This is due to some browsers having problems when setting it to the correct MIME type of the rendition file. File type information can be obtained from the JSON representation of an asset.

410 Gone

This means that the download has failed, usually for one of the following reasons:

  • An internal server error has occurred while processing the rendition(s)
  • The download task was canceled. This does not happen normally.
  • Permissions were changed, and the user no longer has access to the rendition(s)

The client should stop polling the rendition request URL. However, it may attempt to retry the download by creating a new rendition request. If the download failed due to a permission change, then the rendition request will fail immediately with 403 Forbidden (unless permissions were changed again). After repeated failures with 410 Gone during polling, the client should eventually give up retrying the download.