Collection representation

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

Describes the JSON representation of a collection in the FotoWeb RESTful API. There are two representations, one that contains only information about the collection itself, and one that additionally contains part of the content of the collection, such as assets and sub collections.

Usage

Representation of ...

MIME type:

Accept: application/vnd.fotoware.collection+json

Accept: application/vnd.fotoware.collectioninfo+json

Resource(s): All collection resources have this representation, such as archives, albums and search results.

Part of ...

Collection list

Example

Every collection can have a list of assets and a list of sub collections. Sub collections are themselves collections. A typical sub collection relation is between archives and folders. Folders are sub collections of either archives or other folders.

The most basic representation of a collection is application/vnd.fotoware.collectioninfo+json, which only contains general attributes of a collection. It may look as follows:

{
  name: "Photos",
  description: "",
  href: "/fotoweb/archives/5005-Photos/",
  data: "/fotoweb/archives/5005-Photos/",
  type: "folder",
  created: "1601-01-01T00:00:00.000Z",
  modified: "2015-05-26T22:01:08.000Z",
  deleted: null,
  archived: null,
  metadataEditor: {
    name: "Standard Small",
    href: "/fotoweb/editors/4f52e7f5-4d1a-4978-a761-1966acdae434"
  },
  searchURL: "/fotoweb/archives/5005-Photos/{?q}",
  originalURL: "",
  searchString: "",
  taxonomies: [...],
  canHaveChildren: true,
  isSearchable: true,
  isSelectable: false,
  isLinkCollection: false,
  hasChildren: true,
  canCopyTo: false,
  canMoveTo: false,
  canUploadTo: false,
  canCreateFolders: false,
  canIngestToChildren: false,
  canBeDeleted: false,
  canBeArchived: false,
  canCreateAlerts: false,
  isFolderNavigationEnabled: true,
  canSelect: true,
  permissions: [...],
  posterAsset: "/fotoweb/archives/5005-Photos/Photos/Finse%202014/2014-09-14/DSC01804.JPG.info",
  assetCount: 1563,
  childCount: 1,
  ancestors: [...],
  props: {...}  
}

The full representation of a collection, application/vnd.fotoware.collection+json, has additional attributes (highlighted in bold):

{
  name: "Photos",
  
  ...,
  
  assets: {
    data: [...],
    paging: {...}
  },
  children: {
    data: [...],
    paging: {...}
  },
  ancestors: [...],
  props: {...}
}

Attributes

Name	Type	Description
`name`	string	Displayable title of the collection
`description`	string	Long description of the collection
`href`	URL (string), links to a Collection	Canonical public URL of the collection. Please see the remarks section regarding the difference between `href` and `data` URLs.
`data`	URL (string), links to a Collection	User-specific data URL of the collection. Usually, this is the URL that the collection was requested from. In collection lists, this is the URL that should be followed in order to get assets and sub collections of the collection. Please see the remarks section regarding the difference between `href` and `data` URLs.
`uploadHref`	URL (string)	(Deprecated) use `href` URL instead for upload requests. See Uploading assets using the API.
`type`	string	Type of the collection
`created`	date (string)	Date and time on which the collection was created
`modified`	date (string)	Date and time on which the collection last modified. If the collection was never modified, then this is equal to `created`.
`deleted`	date (string)	If not `null`, then the collection has been deleted, and this is the date and time on which the collection was deleted. Unless stated otherwise, a collection list never contains deleted collections, so API clients can ignore this field.
`archived`	date (string)	If not `null`, then the collection has been archived, and this is the date and time on which the collection was archived. Unless stated otherwise, a collection list never contains archived collections, so API clients can ignore this field.
`metadataEditor.name`	string	Display name of the available metadata editor for assets in the collection
`metadataEditor.href`	URL (string) Links to metadata editor	URL of the metadata editor that is available for assets in the collection. The metadata editor is usually defined by the metadata view associated with the archive to which the collection belongs. By sending a request to this URL, a client application can determine what fields are available for editing and other information for editing and validation of metadata input. For more information, please see metadata editors
`searchURL`	URL template (string), Links to a collection	URL template for collection queries (searches) in the collection. By replacing the placeholders in the template with search parameters, a client can search in the collection. If this attribute is `null`, then the collection does not support searching.
`originalURL`	URL (string), Links to a collection	If the collection is a search result, then this is the URL of the collection the search was performed in (without any search parameters).
`taxonomies`	taxonomy list (array of objects)	Contains top-level taxonomy nodes for all metadata fields which are enabled in the API for this collection and which have taxonomy enabled.
`canHaveChildren`	boolean	`true` if this collection may have sub collection, `false` otherwise
`isSearchable`	boolean	`true` if the collection supports search, `false` otherwise
`isSelectable`	boolean	`true` if assets in the collection can be selected in the selection widget, `false` otherwise
`isLinkCollection`	boolean	`true` if this collection is a link collection (e.g., an album), `false` otherwise. See the discussion of link collection in the remarks section about Assets.
`hasChildren`	boolean	`true` if the collection can have sub collections, `false` otherwise
`canCopyTo`	boolean	`true` if it is possible to copy assets to this collection, `false` otherwise. For more information, see Ingestion.
`canMoveTo`	boolean	`true` if it is possible to move assets to this collection, `false` otherwise. For more information, see Ingestion.
`canUploadTo`	boolean	`true` if it is possible to upload assets to this collection, `false` otherwise. For more information, see Ingestion.
`canCreateFolders`	boolean	`true` if it is possible to create new folders when copying, moving or uploading assets to this collection, `false` otherwise. For more information, see Ingestion.
canIngestToChildren	boolean	`true` if there may be sub collections where at least one of `canCopyTo`, `canMoveTo` or `canUploadTo` is `true`, `false` otherwise. For more information, see Ingestion.
`canBeDeleted`	boolean	`true` if it is possible to delete the collection, `false` otherwise. For more information see Deleting a collection (TODO: Link)
`canBeArchived`	boolean	`true` if it is possible to archive the collection, `false` otherwise. For more information see Archiving a collection (TODO: Link)
`canCreateAlerts`	boolean	`true` if it is possible to create alerts in this collection, `false` otherwise
`isFolderNavigationEnabled`	boolean	`true` if folder navigation is enabled in user interfaces for this collection, `false` otherwise
`canSelect`	boolean	`true` if it is possible to select assets in user interfaces for this collection, `false` otherwise
`permissions`	array of strings	List of permissions that the requesting user has on this asset. For possible values, please see Permissions.
`posterAsset`	optional URL (string), Links to asset	URL of the asset which is currently used as poster image for this collection. May be `null`.
`assetCount`	integer	Number of assets in the collection
`childCount`	integer	Number of sub collections in the collection
`ancestors`	array of objects	Lists the collection to which the asset belongs, is parent collection and the remaining ancestors in the collection hierarchy. Can be used for rendering a breadcrumb, implementing an "up" button or finding the collection to which this instance of the asset belongs. For more information, please see ancestor list (TODO: Link)
`props`	object	Common properties of this resource. For more information, see common properties (TODO: Link)
`assets`	asset list (object)	List of assets in the collection
`children`	collection list (object)	List of sub collections in the collection

Remarks

The name and description of a collection come from different sources depending on the type of collection. For archives, name and description can be configured in Operations Center. For albums, name and description can be set by the owner of the album.

In FotoWeb 7, archives and albums used to have numeric IDs. In the FotoWeb RESTful API, the ID of a resource is always its URL. There is no need for getting the numeric ID, and it is not recommended to attempt to extract any IDs from parts of URLs.

Difference between `href` and `data` URLs

Each collection has a canonical public URL (href) and a user-specific data URL (data). This is for caching and access control purposes. The two URLs may be identical or different. In general, the data should be used as request URL for all API requests to a collection. The href URL should be used in the following cases:

Opening a HTML representation of the collection in a browser
Storing the "ID" (URL) of a collection in a database or other persistent storage
Specifying collections in request bodies of API requests

Both URLs of a collection are cacheable resources. When making requests to the href URL, the request user is always Guest. Therefore, no authentication is required. Requesting a collection as guest requires that guest has access to the collection, and that the guest user is enabled. This requires a portal license.

When making requests to the data URL, the request user is the user the client is authenticated as.