[Breaking change]: Delivery API media models and controller namespaces will be changed in Umbraco 13

[kjac]

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

1. The MediaPicker3 value converter MediaPickerWithCropsValueConverter and the IApiMediaWithCropsBuilder service would return instances of the concrete class ApiMediaWithCrops.
2. ApiMediaWithCrops reused models for crops and focal points from the default MediaPicker3 value type.
3. All Media Delivery API controllers would return instances of the concrete class ApiMediaWithCropsResponse.
4. 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

1. MediaPickerWithCropsValueConverter and IApiMediaWithCropsBuilder returns instances of the interface IApiMediaWithCrops.
2. New crops and focal point models have been created for IApiMediaWithCrops - ImageCrop and ImageFocalPoint respectively.
3. All Media Delivery API controllers returns instances of the interface IApiMediaWithCropsResponse.
4. All controllers for the Content Delivery API and the Media Delivery API are moved into dedicated namespaces:
   • Content Delivery API: Umbraco.Cms.Api.Delivery.Controllers.Content.
   • 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

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• 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.

Affected APIs

• MediaPickerWithCropsValueConverter
• IApiMediaWithCropsBuilder
• ByIdContentApiController
• ByIdsContentApiController
• ByRouteContentApiController
• QueryContentApiController
• ByIdMediaApiController
• ByIdsMediaApiController
• ByPathMediaApiController
• QueryMediaApiController