Skip to main content
Documentation & User Guides | Fotoware

Extracting Quick Renditions using the API

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:

  1. Directly request a single asset using its URL. This method can be used if the URL of each asset is already known.
  2. 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.
  3. 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:

quickRenditions: [
  {
    size: 800,
    width: 800,
    height: 600,
    href: "...",
    square: false,
    name: "Web"
  },
  {...},
  ...
]

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/.
  • 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:

def get_quick_rendition_urls(asset_json, name):
  """Iterates over all quick rendition URLs of the asset with the given name"""
  for rendition_json in asset_json['quickRenditions']:
    if rendition_json['name'] == name:
      print(rendition_json['href'])  # Use or return the quick rendition URL

asset_list_json = ...  # Search request (see above)
for asset_json in asset_list_json['data']:
  get_quick_rendition_urls(asset_json, 'Custom')
# If necessary, request more pages of the search result

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.

  • Was this article helpful?