Table of Contents
Downloading asset renditions using the RESTful API
Applies to: FotoWare 8.0 Feature Release 10
04. April 2025
Table of Contents
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
- Download is controlled by permissions. An API client that impersonates a user can only download assets for which the impersonated user has download permission.
- Available renditions are configurable. Site administrators can define processing profiles for each archive that control whether it is possible to download original files, or processed renditions, or both, and which renditions are available.
- Metadata filtering may be performed on downloaded assets. This means that downloaded assets contain only the metadata fields which are configured to be Included in Downloads.
Downloading an asset requires the following steps:
- Obtain a rendition URL
- Create a rendition request
- 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:
|
|
|
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_nameattribute 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, unlessoriginalistrue, 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:
|
|
|
The server returns one of the following responses:
|
|
|
1 |
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:
|
|
|
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.