Ingestion
What is Ingestion?
Ingestion is the process of adding assets to a FotoWeb archive through upload.
Destinations
In order 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 point to a collection list, which is 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 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 which 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 the
canUploadTo
flag is set in the collection information. - Assets can be uploaded to new sub folders in a collection if and only if the
canCreateFolders
flag is set in the collection information.
For all operations, thecanIngestToChildren
flag determines whether there can exist sub collections that are suitable destinations. If this flag is not set, then sub collections do not need to be evaluated recursively to search for destination, because there are none. A user interface for choosing a destination should not display an "expand" button in this case.
Configuring Destinations
This section explains which concrete collections are suitable destinations for ingestion and how to configure it. This is relevant for administrators. API clients can and should simply 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 sub folder 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, then 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 for making upload requests. For more information, see Uploading assets using the API.