Table of Contents
Asset representation
31. March 2025
Table of Contents
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
|
|
|
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, 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, see permissions. |
previews |
array of objects | List of available thumbnail and preview images of this asset. For details, see preview lists |
quickRenditions |
array of objects | List of available quick renditions of this asset. For details, 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, 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, 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, its 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 the 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 the 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:
- All GET requests referring to the instance of the asset in the link collection (and using the access control rules of the link connection) with the asset URL in the URL of the request.
- Following a link from an asset list to an asset
- Removing an asset from a link collection
- Reordering assets in a link collectionUse
hrefin the body of any other requests that perform operations on the asset.
Use href for the following requests and usages:
- Use
hrefin the body of any other requests that perform operations on the asset.