close

Filter

loading table of contents...

Headless Server Developer Manual / Version 2401

Table Of Contents

12.1 Media Endpoint URLs

The media endpoint consists of the following distinct endpoints:

  • Endpoint for images with crops and width.

  • Endpoint for images with crops and width, format transformation and file name.

  • Endpoint for generic media files.

Endpoint for images with crops and width

The first endpoint requests an image by means of the name of the crop and the desired width. The structure of the URI template is as follows:

/caas/v1/media/{mediaId}/{propertyName}/{hash}/{cropName}/{width}

The supported crop names and widths can be retrieved as part of the query for the uriTemplate (see Chapter 12, Media Endpoint). The placeholders 'cropName' and 'width' must be replaced by a valid combination of the supported values. Trying to request an invalid 'cropName' or 'width' will result in an HTTP 404 Not Found error.

Note

Supported combinations of crop names and widths

The names of the crops and the widths are defined in the content repository as part of the Responsive Image Settings. For more information read Section 5.4.14, “Images” in Blueprint Developer Manual .

Endpoint for images with crops and width, format transformation and file name

The second endpoint to request images additionally supports on-the-fly image format transformation and the original file name. The structure of the URI template is as follows:

/caas/v1/media/{mediaId}/{propertyName}/{hash}/{cropName}/{width}/{filename}

The image format is specified by the file extension in the 'filename'. The format transformation is triggered by replacing the file extension with one of the supported image formats 'jpg', 'jpeg', 'png' or 'gif', or by directly requesting the respective uriTemplate like shown in the examples in Chapter 12, Media Endpoint. Requesting an unsupported format will result in an HTTP 400 Bad Request error.

Note

Supported Formats of Cloud Installations

Self-Managed and new Cloud installations since CMCC 11 (2307) differ in terms of supported image formats, image sizes, and image editing capabilities. The features of image editing in a Cloud installation are described in https://documentation.coremedia.com/services/image-transformation/image-transformation-cloud/.

Endpoint for generic media files

The third endpoint is the most generic. It provides access to any media file which is managed by the CMS. The structure of the URI template is as follows:

/caas/v1/media/{mediaId}/{propertyPath}/{hash}[/{filename}]

Note that the filename is optional.

You can comfortably explore the described endpoints using the Swagger UI provided with the overview page.

Content Disposition Header

Whenever a media file is requested with its correct filename (including the file extension), the HTTP header Content-Disposition will be set to inline; filename=<the-original-file-name>.

Placeholders of the media endpoints
mediaId

The content ID of the media/picture.

propertyName

The name of the property, where the blob is stored, usually data.

propertyPath

The name of the property where the blob is stored or the full property path, in case the blob ist stored in a struct.

hash

The hash of the blob. Usually queried via GraphQL.

cropName

The name of an existing crop of an image. Usually queried via GraphQL.

width

An existing width belonging to the crop name. Usually queried via GraphQL.

filename

The file name of a media file, including its file extension. Usually queried via GraphQL.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.