Skip to main content

 

Documentation & User Guides | FotoWare

Export API

There are two ways of using CMS export in integrations:

  • Interactively, by embedding the CMS export widget into a third-party application
  • Automatically, by using the export API.

This article describes how to use the export API.

Programmatic Export using the API

Using the export API assumes that all parameters for exporting an asset are either predefined or already known otherwise (e.g., entered by a user through a custom interface in a third-party application). An asset can then be exported using the following request:

​EXPORT /fotoweb/archives/5000-My%20Archive/Path/to/file.jpg.info
Content-Type: application/vnd.fotoware.export-request+json
Accept: application/vnd.fotoware.export-data+json

with request body:

{
"width": 1234 | 0,
"height": 1234 | 0,
"publication": "http://example.org",
"preset": "/fotoweb/me/presets/exports/539ff28796aede3348c013b2"
}​

where in the request:

Attribute Type Value
width Integer

Width of the exported image (in pixels).

Set to zero (0) to either use the original width or calculate the width from the specified height and original aspect ratio

See remarks and examples in the section "Size and Aspect Ratio".

height Integer

Height of the exported image (in pixels).

Set to zero (0) to either use the original height or calculate the height from the specified width and original aspect ratio

See remarks and examples in the section "Size and Aspect Ratio".

publication String

An identifier of the place where the export is used.

This is a free-form string that will be shown in the export management dialog.

preset URL (String)

URL of a CMS export preset to be used for supplying additional parameters.

API Response

On success, the response is:

200 OK
Content-Type: application/vnd.fotoware.export-data+json

with request body:

{
    "export": {
        "source": "...",
        "json": "...",
        "image": {
            "normal": "...",
            "highCompression": "...",
            "doubleResolution": "..."
        },
        "widget": "...",
        "size": {
            "w": 921,
            "h": 627
        }
    },
    "caption": {
        "label": "...",
        "tooltip": "..."
    },
    "publication": {
        "text": "..."
    },
    "metadata":{
        "FIELD": "VALUE" | ["VALUE1", "VALUE2", ...],
        ...
    }
}

where:

Attribute Type Value
export.source URL (Asset)

URL of the exported asset.

Can be used to access the details of the asset using the API or displaying the details in a browser.

export.json URL (object)

JSON representation of the export.

Identical to this JSON representation

export.image URL (JPEG image) Processed and exported asset (normal version)
export.highCompression URL (JPEG image) Processed and exported asset (smaller file size and potentially reduced quality)
export.doubleResolution URL (JPEG image) Processed and exported asset (doubled resolution, for Retina and similar displays)
export.widget URL (HTML)

An HTML widget containing the processed and exported asset with a tooltip and caption and optional additional behavior, if enabled during export

Can be embedded using an IFRAME.

export.size.w Integer Width of the exported image (normal version) in pixels
export.size.h Integer Height of the exported image (normal version) in pixels
caption.label String Caption string, if specified during export
caption.tooltip String Tooltip string, if specified during export
publication.text String Name of publication (free-form string), if specified during export
metadata Dictionary

Metadata of the asset when it was exported.

The keys in this dictionary are the field numbers (as strings).

The values are either strings (for regular fields) or arrays of strings (for bag fields).

Size and Aspect ratio

The size of the exported image is specified using the width and height parameters in the request.

If both parameters are set to zero (0), then the asset is exported in its original dimensions.

If exactly one of the parameters is non-zero, then that dimension of the exported image will be exactly as specified, whereas the other dimension (given as zero) will be calculated from it such that the original aspect ratio of the image is maintained. For example, if the image is 4:3, and the width in the request is set to 400, the height will be 300.

Note: It is not allowed to set both dimensions to non-zero values. Doing so will result in a response of 400 Bad Request. This is because specifying both dimensions would require cropping the image, which is currently not supported in the export API. Also, if images need to be cropped, you may typically want the user to select a crop frame. In this case, we recommend using the CMS export widget.

If your original images are all a specific known size, e.g., 800x600, and you want images to be exported in that same size, just set both parameters to zero.

Example

Consider exporting a source asset of size 4000x3000:

width

height

Exported width

Exported height

0 0 4000 3000
400 0 400 300
0 600 800 600
400 400 Bad request Bad request

Getting the Preset URL

In order to use a preset with the export API, you must first create an export preset manually and share it.

In order to get the URL of the preset, you can use the development console of the browser while displaying the list of presets in the CMS export dialog, or a web debugging tool such as Fiddler. You should see a GET request to a URL /fotoweb/me/presets/export, which should contain an entry for your preset, such as:

{
  "name": "My preset",  
  "href": "/fotoweb/me/presets/export/5cc6bb338e2ed62920edd536"
    ...
    }

 

The value of the href attribute is the preset parameter to be used in the export API.

Notifications when exported assets change

If you've made an integration using the Export API and would like a notification when an asset changes, you can use asset webhooks to set off this sort of notification.

  • Was this article helpful?