Export API

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

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 (for example, 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 For remarks and examples, see 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 For remarks and examples, see 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 response 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 (800x600, for example) and you want images to be exported in that same size, 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.

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.