Image Service
Overview
Image Service is a Mosaic Managed Service. Its purpose is to manage images and transform them into the formats requested by the frontend applications. Images can be uploaded to the Image Service via its GraphQL API or fetched by the Image Service from external storage. Images are assigned an Image Type, interpreted by the frontend applications, and optionally tagged with arbitrary tags.
Once in the Image Service, the images can be requested in any format, defined by:
-
image resolution (width, height)
-
focal point (a center around which to cut an image)
-
image format (JPEG, PNG, WebP).
Using a CDN, it is possible to drastically reduce traffic to the Image Service by storing the transformation results on the edge servers near the customers. Image Service comes with a Micro-Frontend for managing and uploading images. It plugs seamlessly into the Management System where it can be used together with other Mosaic Services. Image Service exposes frontend extensions that any other Mosaic Service can use to select an image and to render an image preview.
See also: Optimizing Images for an OTT Platform
Data Model
Image. Image has a file (stored in internal storage) and metadata. Image is immutable. If a change is required, a new image shall be uploaded. This is to prevent unexpected consequences of an image change for existing usages.
Images can be uploaded in a number of ways:
-
Interactively, using a GUI
-
Synchronously, using GraphQL API
-
Asynchronously, from a configured image storage, using Messaging.
Image Type. Every Image shall be assigned to an Image Type. Image Types can be defined by any other service (using Messaging). Image Type has no semantic in the context of the Image Service, but they can be interpreted by the owning service.
Image Tag. Users can tag Images. Other services can give meaning to the tags.
Interfaces
Image Transformation API
Image representations are generated on the fly by applying the necessary transformations. There is no need to define the formats in advance and pre-generate images. To reduce the load on the Image Service we highly recommend using a CDN.
The Image Transformation API provides a single endpoint /transform accessible with an HTTP GET verb.
The request shall be formatted as seen below:
https://image.service.eu.axinom.net/transform/$environment-specific-identifier/$filename?parameter=value
The URL parameters are:
| Parameter | Comment | Example |
|---|---|---|
environment-specific-id |
contains the tenantId and environmentId |
16b0tks5rqq2qoobqvo5fxhfj-8j0cretxi7muq1cgjvp4fwurw |
filename |
image filename |
WXe4hVRanMNaAPsXtmMX6E.jpg |
w,h |
desired width/height in px |
400 |
f |
desired image format |
'jpg', 'png', or 'webp' |
focalX, focalY |
focal point, decimal between 0 and 1 |
0.2 |
Example:
https://image.service.eu.axinom.net/transform/16b0tks5rqq2qoobqvo5fxhfj-8j0cretxi7muq1cgjvp4fwurw/WXe4hVRanMNaAPsXtmMX6E.jpg?w=400&h=100&focalX=0.2&focalY=0.9&f=webp
It is enough to specify either the width or the height of the image. The other dimension will be calculated based on the original aspect ratio. Consider that if asked for the dimensions beyond the size of the original, the service will deliver the original size instead.
|
Note
|
To find out the environment-specific-id and filename for a specific image, you can query the GraphQL API. Alternatively, in the Image Service Micro-Frontend you can go to the "Image Detail" station and then to "Focal Point", and then "Copy image address" from either the main image or one of the transformation examples on the right.
|
GraphQL Admin API
This API provides read- and management access to all data inside the Image Service.
To use the API you need a JWT from the Admin Service.
See also: How to authenticate a service account.
Image Upload
GraphQL mutation uploadImage can be used to upload a new image.
Parameters:
-
Image File
-
Image Type.
|
Tip
|
Altair endpoint - https://image.service.eu.axinom.net/altair/ - can be more convenient interface to upload files via GraphQL. |
Messaging
Image Service supports a number of commands and events.
See also: Messaging.
Server-side Download
There is a command initiating image download from a configured image storage.
Parameters:
-
Image relative path in the image storage (e.g. "/images/covers/avatar.jpg")
-
Image type that defines which image formats to create (e.g. "movie_cover").
-
Optionally, a list of tags to add to the image
-
Optionally, a correlation ID.
Ingest
Ingest feature implemented in the Media Service allows to create and link an image (cover) for each ingested entity downloading them from a pre-configured Image Storage. Ingest uses the interface described above under Server-side Download.
GUI
Image Service comes with a Micro-Frontend for managing and uploading images. It plugs seamlessly into the Management System where it can be used together with the other Mosaic Services.