Table of Contents
Extracting Quick Renditions using the API
11. April 2025
Table of Contents
This article describes how to use the API to extract renditions (images) of assets, which have sizes and other attributes (such as quality and watermark settings) which can be set by the system administrator. This allows an integration to export large numbers of images from a FotoWeb system into a third-party system, such as a web shop or gallery.
Configuration
To make custom renditions available to the API, the system administrator has to set up one or more quick renditions and assign them to one or more archives. For more information, see how to create Quick Renditions.
API clients get access to the same quick renditions as users in the web interface, provided that the user making the requests is an administrator or has the Quick Renditions permission on the archive the assets are exported from. Therefore, no additional configuration step is needed if API requests are made as administrator (server-to-server authentication). However, if API requests are made as guest (unauthenticated public API) or as an impersonated user, then the guest user or the impersonated user (or one of the user's groups) must have this permission enabled in the access list of the archive. For more information, see Setting Archive Access and Permissions.
Note that FotoWeb also exports some default size images (preview images) for each image. If these match the integration requirements, then it is unnecessary to set up quick renditions and provide quick rendition permission. For more information about getting preview images using the API, see Getting Previews.
Remarks
Preview and quick rendition URLs are ephemeral, i.e., they have a limited lifetime and are designed to be used immediately. They are NOT designed for long-term storage or embedding. Immediately here means within a few seconds or minutes, whereas “long-term” means within hours or days or permanent.
This means that the following usages of rendition URLs are safe:
Immediately showing the rendition image in the UI of a native application
Immediately downloading the rendition image for storage or further processing in a third-party component
Embedding the rendition URL in an ephemeral / dynamically generated web view.
whereas the following usages of rendition URLs are NOT safe:
Storing the rendition URL in a third-party component for a longer time
Embedding the rendition URL in a web view that is expected to remain valid long-term, such as a blog post or static website.
To obtain embeddable rendition URLs that remain valid long-term, please consider using CMS export or the Export API.
Accessing rendition URLs does not require authentication or access tokens, so they can be embedded into (short-lived) web views without the need to expose access tokens to user agents. Rendition URLs are protected by signatures to prevent unauthorized access. A valid rendition URL can only be obtained via the FotoWeb API or UI by authorized clients or users.
It is not possible for integrations to construct valid rendition URLs themselves. The format, signature algorithm, expiry time, and expiry conditions for rendition URLs are implementation-defined and subject to change, and any information provided about these by Fotoware is for review or debugging purposes only. Under no circumstances should integrations rely upon them. If you need a way to produce valid rendition URLs in an integration, submit a feature request to Fotoware. Note that the Preview Agent API is deprecated and should not be used in new integrations.
Getting Quick Rendition URLs
To export images, an API client must get the quick rendition URL of each image. This is done by requesting the JSON data of all the assets that should be exported and then extracting quick rendition URLs from the JSON data.
Requesting Asset Information
Requesting JSON data about assets is possible in different ways:
- Directly request a single asset using its URL. This method can be used if the URL of each asset is already known.
- Request and traverse the asset list of an archive, album, or other type of collection. This method can be used if all or most assets in a collection should be exported.
- Do a collection query (search) request and traverse the result list. This method can be used when exporting assets matching certain search criteria.
Method 1 produces the JSON representation of a single asset. For more information, see Asset Representation.
Methods 2 and 3 produce a list of assets that need to be traversed, possibly using multiple requests. For more information, see Asset List Representation.
Quick Rendition List
Either way, each method produces the JSON representation of one or more assets. Each of these contains the quickRenditions attribute, which is a list of available quick renditions and has the following format:
|
|
|
Each element of the list has the following attributes:
| Name | Type | Description |
|---|---|---|
size |
integer | Size of the image. This is the maximum of its width and its height in pixels. |
width |
integer | Width of the image in pixels |
height |
integer | Height of the image in pixels |
href |
string (URL), links to image | URL of the rendition image |
square |
boolean |
true if the image has equal width and height, false otherwise. |
name |
string | Name of the quick rendition, as set in the configuration |
The name and size attributes can be used to select the wanted quick rendition out of the list. For example, the name can be a keyword (set by the system administrator) in both the FotoWeb configuration and the configuration of the API client extracting the images. If each quick rendition has a different size, then the size attribute can be used as a selector.
The href attribute refers to the actual image. These images are generated on demand and cached on the server side.
Example
This section explains the full process of exporting images using quick rendition with a concrete example. In this example, assets are exported from a single archive if they match a search query.
Step 1: Configure Quick Renditions
- Follow the instructions here to create a quick rendition of size 800 with name "Custom"
- Assign the quick rendition to an archive
Step 2: Search for the Assets
- Determine the URL of the archive to search in, either manually in the web interface or using the API.
- In this example, the archive URL is:
/fotoweb/archives/5000-Example/.
- In this example, the archive URL is:
- Make the following request to search for assets matching a full-text search query:
GET /fotoweb/archives/5000-Example/?q=searchText Accept: application/vnd.fotoware.assetlist+json
This returns JSON data, which contains the quickRendition URLs. These can be extracted as follows:
|
|
|
The Python script above extracts and prints the quick rendition URLs of the quick rendition called "Custom" created in step 1 for each asset in the search result. For simplicity, it does not handle paging of the returned asset list, so this code is only guaranteed to return the first (newest) asset in the result set.
A real application might, for example, store the quick rendition URLs along with the asset URLs (asset_json['linkstance']) in a database for later use. The asset URLs are needed to recreate the quick rendition URLs later in case of changes.