Destination Lists

The full API descriptor provides links to three collection lists in the following attributes:

Each of these links points to a collection list called a destination list. They contain all possible top-level upload destinations (typically archives and/or the upload area) as sub-collections. These can then be browsed hierarchically in the usual way to find suitable destinations.

The following example shows a request to get the top level of upload destinations:

GET /fotoweb/me/upload-to/
Accept: application/vnd.fotoware.collectionlist+json
200 OK
Content-Type: application/vnd.fotoware.collectionlist+json
{
 data: [ ... list of collections ... ],
 paging: null
}

The request to get all sub-collections of a collection is the same, except the request URL is replaced by the URL (given in the data attribute) of the collection whose sub-collections to get.

What is a Destination?

A suitable destination is a collection that allows assets to be added using a specific operation (move, copy, or upload).

Note that not all collections discovered through a destination list are destinations. However, by hierarchically browsing these destination lists, an application can find all destinations for the given operation. The following conditions must be checked, depending on the type of operation, to determine if a collection is a suitable destination:

For upload, there are special rules:

• A collection is an upload destination if and only if thecanUploadToflag is set in the collection information.
• Assets can be uploaded to new subfolders in a collection if, and only if, the canCreateFolders flag is set in the collection information.

For all operations, thecanIngestToChildrenflag determines whether sub-collections that are suitable destinations can exist. If this flag is not set, sub-collections need not be evaluated recursively to search for a destination because there are none. In this case, a user interface for choosing a destination should not display an "expand" button.

Configuring Destinations

This section explains which concrete collections are suitable destinations for ingestion and how to configure them. This is relevant for administrators. API clients can and should discover upload destinations as described in the previous sections.

• An archive itself is a destination only if the archive has a custom ingestion folder
• A folder in an archive is a destination only if it is a physical folder. A physical folder is one of the following:
  • A document folder of a regular index
  • A document folder of a union member
  • A subfolder of another physical folder
• The user's upload area is a suitable destination only if it is enabled for the request user
• In addition to the rules above, the request user must have permission to ingest to an archive.

If an archive has a custom ingestion folder, it is only possible to ingest to the archive itself, not to any folders in it. Therefore, the canIngestToChildren flag is false.

It is not possible to create folders in the upload area. Therefore, canCreateFolders is set to false.