Media albums and items

General API
, ,
1

Background

Media albums and items belong to cases in RealEquity. You can create media albums and media items on a case, move items in and out of albums, update albums and items, and delete them if they’re no longer required.

Media albums are essentially logical containers for media items. The type of album describes how the album, and its items, are supposed to be used. For example, a portal album will contain media items that have been prepared for use with an online real-estate portal such as Boligsiden. Media items aren’t meant to be retrieved and used directly.

Media items are logical containers for raw media files such as images and video. The type of media item describes the content type of the contained media file as well as where it’s stored. Media items can be stored locally within RealEquity or externally with a media server provider.

Media albums

A media album is a logical container representing a selection of media items and a sort order that these should be presented in.

:no_entry: It’s only possible to create one album of each type. Otherwise, integrators wouldn’t know which album to pick.

There are four types of media albums:

Type Namespace Use case
Main dk.realequity.mediaalbum.main The main album for the case, used by home pages.
Display dk.realequity.mediaalbum.display Used by physical in-store display solutions.
Portal dk.realequity.mediaalbum.portal Used by real-estate portals like Boligsiden.
Sale dk.realequity.mediaalbum.sale Used for generation of sale presentations.

Integrators should always retrieve media items by retrieving the appropriate album for the use case. External home pages should always retrieve the main album. The first media item of the main album will be the main photo representing the case. In all other use cases, integrators should attempt to retrieve the appropriate album for the use case, and if no such album exist, fall back to the main album instead.

API operations

See Media albums in the API reference.

:warning: The “Add media item” and “Remove media item” operations are obsolete and will be removed. Use the Update media album operation to add and remove media items to and from media albums.

Get media album
Polymorphic operation returning a media album including a list of it’s media items, which can be a mix of either images, image references, or videos, of the respective namespaces described below.

Create media album
When creating a media album, all you need to supply is a type (namespace) and a display name:

{
"namespace": "dk.realequity.mediaalbum.sale",
"displayName": "Salgsopstilling"
}

Update media album
When updating a media album, you can change the display name and the list of media items to include in the album:

:warning: You cannot add media items to a media album or remove items from it. Instead you overwrite the entire album in one operation, essentially replacing its list of items with a new one. The order of item ids in the list determine the sort order of the items in the album.

The update payload:
Notice the order of item ids in the list.

{
    "displayName": "Hovedalbum",
    "mediaItemIds": [
        "9a123aec-fdb9-4223-90fe-8edb94cc559e",
        "370e182a-cb2b-4750-8c6d-921145f3ddad"
    ]
}

The updated media album:
Notice how the order of items in the album correspond to the order of item ids in the update payload. The order is respected by the user interface.

{
    "displayName": "Hovedalbum",
    "id": "7a35ff02-b901-48c8-8253-4db6a4c73a4b",
    "mediaItems": [
        {
            "originalFileName": null,
            "lgUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_9a123aec-fdb9-4223-90fe-8edb94cc559e/lg",
            "mdUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_9a123aec-fdb9-4223-90fe-8edb94cc559e/md",
            "xlUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_9a123aec-fdb9-4223-90fe-8edb94cc559e/xl",
            "smUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_9a123aec-fdb9-4223-90fe-8edb94cc559e/sm",
            "xsUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_9a123aec-fdb9-4223-90fe-8edb94cc559e/xs",
            "size": null,
            "contentType": null,
            "originalSize": null,
            "originalContentType": null,
            "id": "9a123aec-fdb9-4223-90fe-8edb94cc559e",
            "displayName": "Drawing 2",
            "description": null,
            "namespace": "dk.realequity.mediaitem.image.drawing"
        },
        {
            "originalFileName": null,
            "lgUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_370e182a-cb2b-4750-8c6d-921145f3ddad/lg",
            "mdUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_370e182a-cb2b-4750-8c6d-921145f3ddad/md",
            "xlUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_370e182a-cb2b-4750-8c6d-921145f3ddad/xl",
            "smUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_370e182a-cb2b-4750-8c6d-921145f3ddad/sm",
            "xsUrl": "https://imagedelivery.net/_jfsw0_xWJwHgh0HZwP0ZQ/int_370e182a-cb2b-4750-8c6d-921145f3ddad/xs",
            "size": null,
            "contentType": null,
            "originalSize": null,
            "originalContentType": null,
            "id": "370e182a-cb2b-4750-8c6d-921145f3ddad",
            "displayName": "Drawing 1",
            "description": null,
            "namespace": "dk.realequity.mediaitem.image.drawing"
        }
    ],
    "namespace": "dk.realequity.mediaalbum.main"
}

Delete media album
When deleting a media album, you supply it’s id as a query param.

Media items

A media item is a logical container representing a raw media file. There are essentially 4 types of media items, but 3 of them exist in two versions, a version representing a locally stored media file and a version representing a file stored on an external media server.

:no_entry: A media item’s type cannot be changed. For example, a locally stored photo cannot be “updated” to become a locally stored map, a remotely stored photo or a video.

Media items representing files stored in RealEquity

Type Namespace Description
Drawing dk.realequity.mediaitem.image.drawing Represents a technical drawing stored in RealEquity.
Map dk.realequity.mediaitem.image.map Represents a map stored in RealEquity.
Photo dk.realequity.mediaitem.image.photo Represents a photo stored in RealEquity.
Video dk.realequity.mediaitem.video.default Represents a video.

Media items representing files stored on external media servers

Type Namespace Description
Drawing dk.realequity.mediaitem.imageref.drawing Represents a technical drawing stored on an external media server.
Map dk.realequity.mediaitem.imageref.map Represents a map stored on an external media server.
Photo dk.realequity.mediaitem.imageref.photo Represents a photo stored on an external media server.

API operations

See Media items in the API reference.

Get media items on case
Polymorphic operation returning a list of media items on a case. The list can contain a mix of either images, image references, or videos, of the respective namespaces described above.

Create media item on case
Polymorphic operation. When you create a media item on a case, you must post a model of either an image, an image reference, or a video, of the respective namespaces described above. It’s the type of model that determines the properties available and required.

Download original content from media item
Downloads the original content from a media item on a case. It only works for media items stored locally in RealEquity. Referenced media items must be retrieved directly from the media server provider.

Get media item
Polymorphic operation. Gets an image, image reference, or video media item.

Update media item
Polymorphic operation. Makes it possible to change the display name and description of a media item.

Delete media item
Deletes a media item from a case.

Upload content to media item
Once a media item has been created, this operation is used to upload its original content.