Headless Server Developer Manual / Version 2401
Table Of ContentsThe 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.
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.
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.