Skip to main content

 

Documentation & User Guides | FotoWare

Collection representation

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

or

Accept: application/vnd.fotoware.collectioninfo+json

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

Part of ...

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.

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 set 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 (TODO: Link)

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. 

  • Was this article helpful?