Integrator's guide to FotoWeb Drag and Drop export

Overview

Enabling drag & drop export of assets to a specific desktop application requires writing a custom-made integration for the each application. The integration must be built into the desktop application or a plugin or "proxy application" that talks to the actual desktop application. It must do the following:

1. Receive and handle drag events using the desktop interface (Windows or Mac OS), which contain URLs of dropped assets or asset selections
2. Send request to the URL resolver service of FotoWeb to get metadata and original files based on the dropped URLs.

Definitions

• Drop Target: Part of the user interface of the desktop application (or a plugin or proxy application) on which assets can be dropped
• URL resolver: Part of the custom integration made in the desktop application which requests metadata and original files from FotoWeb based on URLs dropped on a drop target
• URL resolver service: An API in FotoWeb that is used by an URL resolver

Note: The format of the drop URLs is unspecified. The desktop application never needs to interpret drop URLs. It merely passes them on to the URL resolver service. Note that it is not possible to compute the drop URL of another asset using a given valid drop URL. This is by design and necessary for access control, so users cannot access information about assets without permission. We therefore strongly discourage any attempts at interpreting or reverse-engineering drop URLs. 

URL Resolver API

Once the desktop application has received an URL on the drop target, the URL must be resolved using the URL resolver service of FotoWeb.

The URL resolver service is used as follows:

GET /fotoweb/services/urlresolver?url=DROP_URL
Accept: application/vnd.fotoware.assetlist+json

where DROP_URL is the drop URL that was received on the drop target.

Note: The DROP_URL parameter must be URL-encoded (just like any string value that is put into a query string parameter). Even though it already is an URL and might already contain percent-encoded characters, it must be encoded again, since an URL contains characters that have special meanings inside URLs. After correct encoding, for example, the protocol part ("https://") looks like this: "https%3A%2F%2F".

If the request fails, the status code in the response can be interpreted as follows:

• 400 Bad Request: The drop URL is invalid or the user did not have permission to use drag & drop export (can occur particularly when dragging a single asset from the standard interface without the necessary permissions and license)
• > 500: An internal error has occurred on the server. The user may attempt to retry the operation later. If this continues to occur, then the server is either misconfigured or it is a bug. In this case, we recommend contacting Fotoware support.

If the request is successful, the service responds as follows:

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


{...}

The body of the response is an asset list represented in JSON, which is the format also used for asset lists in the FotoWeb REST API.

The response contains metadata and (if configured ) URLs of quick renditions, which can be used for extracting images.

POST Requests

For large numbers of assets, we strongly recommend using POST requests rather than GET requests to the URL resolver, due to URL length limitations. 

POST /fotoweb/services/urlresolver
Accept: application/vnd.fotoware.assetlist+json
Content-Type: application/vnd.fotoware.assetlinklist+json

POST /fotoweb/services/urlresolver Drop URLs are the same kind of URLs that are passed to the url argument in the GET request. Multi-asset URLs are also supported. This means that if a multi-asset URL was dropped on the drop target, then the client can simply send:

Accept: application/vnd.fotoware.assetlist+json
Content-Type: application/vnd.fotoware.assetlinklist+json


{
  "data": [ {"href": "DROP_URL"} ]
}

This request supports sending multiple drop URLs.

Although the MIME type application/vnd.fotoware.assetlinklist+json is used in the request, only drop URLs are allowed, so this is not a regular asset link list.

The format of a drop URL is unspecified. Applications MUST NOT make any assumptions about the format of drop URLs, parse them or compose new drop URLs. This is not supported and may break in future versions if new ways to export assets are added to FotoWeb or the URL format changes. Drop URLs should not be stored in external applications. Instead, they should be sent to the URL resolver as soon as possible. The responses returned by the URL resolver, as well as renditions of assets, may be stored.