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

In order 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 administrator or has the Quick Renditions permission on the archive the assets are to be exported from. Therefore, if API requests are made as administrator (server-to-server authentication), no additional configuration step is needed. 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 a number of default size images (preview images) for each image. If these match the requirements of the integration, then it is not necessary to set up quick renditions and provide quick rendition permission. For more information about getting preview images using the API, please see Getting Previews.

Getting Quick Rendition URLs

In order to export images, an API client must get the quick rendition URL of each image. This is done by first 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, which needs 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.

Using Quick Rendition URLs

The quick rendition URLs can be used directly to request and download the image. Alternatively, they can be embedded in third-party web sites and stored in databases.

However, if a quick rendition URL is exported or stored in a third-party system, it is important to take the following in consideration:

  • Changing the attributes of a quick rendition also changes the URLs. An URL extracted earlier will still be valid but also still produce the same image (with the old attributes). This is inevitable in order to achieve good caching.
  • All URLs may change when upgrading to a new FotoWeb version (although this normally does not happen).
  • Images are requested from the FotoWeb server, so the server must be running and stable all the time and be able to handle the load. If this can not be guaranteed, then it may be more suitable to download the images and make them available through a CDN.

When storing quick rendition URLs in a third-party system, then we recommend storing also the asset URL for each image. This URL can later be used to re-extract the new quick rendition URLs using the API if changes have been made to quck rendition configuration or if FotoWeb has been upgraded.

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 be able to recreate the quick rendition URLs later in case of changes.

  • Was this article helpful?