Umbraco 12.2 ships with the Media Delivery API to complement the Content Delivery API. While building the Media Delivery API, certain compromises were made to keep Umbraco 12.2 backwards compatible.
These compromises will be addressed in Umbraco 13.
Version
Umbraco 13
Previous behavior
The MediaPicker3 value converter MediaPickerWithCropsValueConverter and the IApiMediaWithCropsBuilder service would return instances of the concrete class ApiMediaWithCrops.
ApiMediaWithCrops reused models for crops and focal points from the default MediaPicker3 value type.
All Media Delivery API controllers would return instances of the concrete class ApiMediaWithCropsResponse.
All controllers for the Content Delivery API and the Media Delivery API were located in the same namespace (Umbraco.Cms.Api.Delivery.Controllers).
New behavior
MediaPickerWithCropsValueConverter and IApiMediaWithCropsBuilder returns instances of the interface IApiMediaWithCrops.
New crops and focal point models have been created for IApiMediaWithCrops - ImageCrop and ImageFocalPoint respectively.
All Media Delivery API controllers returns instances of the interface IApiMediaWithCropsResponse.
All controllers for the Content Delivery API and the Media Delivery API are moved into dedicated namespaces:
Media Delivery API: Umbraco.Cms.Api.Delivery.Controllers.Media.
IApiMediaWithCrops and IApiMediaWithCropsResponse are new interfaces introduced in Umbraco 13.
As part of this change, ApiMediaWithCrops and ApiMediaWithCropsResponse are made internal.
Type of breaking change
[X] Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
[X] Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.
Reason for change
This change aligns the modelling of the Media Delivery API with that of the Content Delivery API. Furthermore, this change allows for greater flexibility in customising the output of media items within both APIs.
The controller namespace changes create a better structure and foundation for future development of the Delivery API.
Recommended action
Use the new interfaces instead of the concrete classes.
Adjust namespaces if any Delivery API controllers have been referenced.
Description
Umbraco 12.2 ships with the Media Delivery API to complement the Content Delivery API. While building the Media Delivery API, certain compromises were made to keep Umbraco 12.2 backwards compatible.
These compromises will be addressed in Umbraco 13.
Version
Umbraco 13
Previous behavior
MediaPickerWithCropsValueConverterand theIApiMediaWithCropsBuilderservice would return instances of the concrete classApiMediaWithCrops.ApiMediaWithCropsreused models for crops and focal points from the default MediaPicker3 value type.ApiMediaWithCropsResponse.Umbraco.Cms.Api.Delivery.Controllers).New behavior
MediaPickerWithCropsValueConverterandIApiMediaWithCropsBuilderreturns instances of the interfaceIApiMediaWithCrops.IApiMediaWithCrops-ImageCropandImageFocalPointrespectively.IApiMediaWithCropsResponse.Umbraco.Cms.Api.Delivery.Controllers.Content.Umbraco.Cms.Api.Delivery.Controllers.Media.IApiMediaWithCropsandIApiMediaWithCropsResponseare new interfaces introduced in Umbraco 13.As part of this change,
ApiMediaWithCropsandApiMediaWithCropsResponseare madeinternal.Type of breaking change
Reason for change
This change aligns the modelling of the Media Delivery API with that of the Content Delivery API. Furthermore, this change allows for greater flexibility in customising the output of media items within both APIs.
The controller namespace changes create a better structure and foundation for future development of the Delivery API.
Recommended action
Use the new interfaces instead of the concrete classes.
Adjust namespaces if any Delivery API controllers have been referenced.
Affected APIs
MediaPickerWithCropsValueConverterIApiMediaWithCropsBuilderByIdContentApiControllerByIdsContentApiControllerByRouteContentApiControllerQueryContentApiControllerByIdMediaApiControllerByIdsMediaApiControllerByPathMediaApiControllerQueryMediaApiController