Skip to main content

 

Documentation & User Guides | FotoWare

Asset representation

This article describes the JSON format that represents an asset in the FotoWeb RESTful API. This is the application/vnd.fotoware.asset+json media type. It is also used as part of the representation of an asset list.

Usage

Representation of ...

MIME type:

Accept: application/vnd.fotoware.asset+json

Resource(s): All asset resources have this representation. This includes assets in all kinds of collections, such as archives, albums and search results.

Part of ...

Example

{
  href: "/fotoweb/archives/5005-Photos/Photos/Trollheimen/2014-07-24/DSC01639.JPG.info",
  archiveHREF: "/fotoweb/archives/5005-Photos/",
  linkstance: "/fotoweb/archives/5005-Photos/Photos/Trollheimen/2014-07-24/DSC01639.JPG.info",
  created: "2014-09-17T08:57:40.000Z",
  modified: "2014-09-17T08:57:45.000Z",
  filename: "DSC01639.JPG",
  filesize: 7196672,
  uniqueid: "",
  doctype: "image",
  permissions: [ "View", "Download" ],
  previews: [...],
  quickRenditions: [...],
  metadataEditor: {
    name: "Standard Small",
    href: "/fotoweb/editors/4f52e7f5-4d1a-4978-a761-1966acdae434"
  },
  renditions: [...],
  attributes: {
    imageattributes: {...},
    photoAttributes: {...},
  },
  metadata: {...},
  ancestors: [...],
  props: {...}
}

Attributes

Name

Type

Description

href

URL (string)

Links to asset

Original URL of the asset within the originating archive. This URL is used for most workflow operations. See also linkstance.

archiveHREF

URL (string)

Links to archive

URL of the archive which contains the asset. Each asset is contained in only one archive. If the asset was discovered in a different kind of collection (such as an album, a search result or a folder), then this attribute can be used for finding the root URL of the original archive.

linkstance

URL (string)

Links to asset

URL of this instance of the asset. An asset may belong to more than one collection, such as an archive or an album. Access rights and other properties of the same asset may differ between different collections. The asset is then said to have multiple instances, one instance per distinct collection. For archives and folders, linkstance is always identical to href, which is called the original instance of the asset. Use linkstance to follow links from asset lists to individual assets.

created

date (string)

The date and time on which the asset was created

modified

date (string)

The date and time on which the asset was last modified

filename

string

Name of the file without path

filesize

integer

Size of the file in bytes

uniqueid

string

Unique ID of the asset. This ID is globally unique and created by IndexManager upon indexing

doctype

string

Type of this asset. For possible values, please see document types. This attribute determines which sub sections of the attributes section are present.

permissions

array of strings

List of permissions that the requesting user has on this asset. For possible values, please see permissions.

previews

array of objects

List of available thumbnail and preview images of this asset. For details, please see preview lists

quickRenditions

array of objects

List of available quick renditions of this asset. For details, please see Extracting Quick Renditions.

metadataEditor.name

string

Display name of the available metadata editor for this asset

metadataEditor.href

URL (string)

Links to metadata editor

URL of the metadata editor that is available for this asset. The metadata editor is usually defined by the metadata set associated with the archive to which the asset 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

renditions

array of objects

List of available renditions of this asset. Renditions are used for downloading assets, either original or processed. For more information, please see renditions.

metadata

object

Contains values of metadata fields of this asset which are exposed by the API. Usually, the metadata set associated with the archive to which the asset belongs controls which fields are available.

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.

props

object

Common properties of this resource.

attributes.imageattributes

optional object

If present, contains information specific to image assets, such as resolution and color space.

attributes.photoAttributes

optional object

If present, contains camera information based on EXIF data, such as camera model and exposure.

attributes.videoattributes

optional object

If present, contains information specific to video assets, such as frame rate and codec.

attributes.documentattributes

optional object

If present, contains information specific to document assets, such as number of pages.

Remarks

Information returned about an asset may vary depending on the user that is making the request. In particular, the permissions and previews fields may contain different values for different users. They reflect the permissions that the requesting user has on the asset and the types of previews (size, watermarked or not watermarked, etc.) that are available to that user.

The doctype field determines what subsections are present in the attributes section. For example, if the doctype is "image", then attributes.imageattributes is always present. However, it is recommended to explicitly check for presence of these subsections instead whenever they are used. This makes application code more flexible. For example, it can be used for all types of assets that contain image attributes, not only those of type "image".

Using href and linkstance

Each asset belongs to exactly one archive and has exactly one location (folder path and file name) in that archive. This is called the original instance of the asset. It represents the physical file that is behind the asset and provides read and write access to all users with the required permissions. The archive to which an asset belongs is called the originating archive of the asset.

An asset may also be added to other collections which do not represent physical files but only refer to physical files or assets in archives. For example, an asset may be added to one or more albums. if an asset is contained in one or more albums, then there exists one additional instance for each album that the asset is contained in. These instances are also said to be link instances to the original instance, and albums (and some other collection types), which only contain link instances are called link collections.

Every instance of an asset is a separate resource with its own unique URL. The URL of the original instance is returned in href, and the URL of the requested link instance is returned in linkstance. If an asset representation is requested using the URL of the original instance (href) or contained in an asset list requested from the originating archive or a folder in it, then href and linkstance are identical. If an asset is contained in an asset list requested from a link collection, then href and linkstance are different. If an asset representation is requested from an instance of an asset, linkstance is always identical to the request URL.

This is for the following reasons:

  • The same user may have different permissions on different instances of the same asset. These permissions usually depend on permissions on the originating archive, on the album and other factors.
  • When a link instance of an asset is deleted (using a DELETE request), then the asset is removed from the link collection only. When the original instance of an asset is deleted, then the asset is deleted from the originating archive and all other collections it belongs to. The physical file behind the asset and all other references to the asset are purged from the system.

When an asset is moved or renamed in the originating archive, then href may change, whereas linkstance remains the same in all link collections.

Use linkstance for the following requests and usages:
  • Following a link from an asset list to an asset
  • Removing an asset from a link collection
  • Reordering assets in a link collection
Use href for the following requests and usages:
  • Workflow operations such as actions
  • File operations, such as deleting, moving, copying, renaming
  • Was this article helpful?