Skip to main content
Documentation & User Guides | Fotoware


What is Ingestion?

Ingestion is the process of adding assets to a FotoWeb archive through upload.


To ingest assets, an application must specify a destination. This is typically a folder in an archive, but it can also be a different kind of collection, such as the user's upload area.

Destination Lists

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

upload_to: "/fotoweb/me/upload-to/",

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.

Ingesting Assets

Once a destination has been found, the href  attribute of the destination collection can be used to make upload requests. For more information, see Uploading assets using the API.

  • Was this article helpful?