---
title: Breaking changes in version 3
slug: cms-12/api/breaking-changes-version-3
docTags: 
createdAt: 2026-08-07T16:45:43.000Z
---

A breaking change may cause a component to fail. When a breaking change is made to a signature of a method, class, or interface, the former signature is often kept intact but set as obsolete and may cause a warning message in Visual Studio. To delay fixing the warning messages, you can disable **Treat Warnings as Errors**. Right-click on your project and go to **Properties** > **Build** > set **Treat Warnings as Errors** to **Specific warnings** or **None**.

Classes that expose constructors that take dependencies are normally deleted without an obsolete warning in major releases because the compiler provides information about what you need to change. Keeping those classes makes dependency injection complex because, over time, there would be multiple constructors to choose from that might overlap.

In each major version, obsolete methods are removed permanently to keep the API clean and usable. If you could postpone fixing warning messages, you should make sure warning messages are fixed before upgrading to a major version. For version 3, some methods that were made obsolete in prior versions are now deleted.

## Configuration

| Version 2                  | Version 3                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `ContentApiConfiguration`  | Obsoleted. Use `ContentApiOptions` directly instead.                                                            |
| `Clients`                  | Obsoleted. Use the built-in CORS middleware instead; see CORS in [Configuration](docId\:rEKDgayvgt9oP2aovJhO5). |
| `ExtendedContentTypeModel` | Removed.                                                                                                        |
| `IncludeNullValues`        | Obsoleted. Use `IncludeEmptyContentProperties` instead.                                                         |
| `MinimumRoles`             | Obsoleted. Use `ContentDeliveryApiOptions.AllowedScopes` instead to control who can make API calls.             |
| `RequiredRole`             | Obsoleted. Use `ContentDeliveryApiOptions.RequiredRole` and `ContentApiSearchOptions.RequiredRole` instead.     |
| `SiteDefinitionApiEnabled` | Obsoleted. Use `ContentDeliveryApiOptions.SiteDefinitionApiEnabled` instead.                                    |
| `Set`\*                    | All "`Set`" methods were removed.                                                                               |

## Changes in class namespaces

In version 3, many classes were moved to internal namespaces, removed, or made public for behavior customization. This section describes the changes, grouped by the most common customization scenarios.

### Customize content conversion

The main flow of content conversion can be described as follows:

- Content is acquired by `ContentLoaderService`
- `ContentConvertingService` uses `ContentModelMapper` and `UrlResolverService` to convert `IContent` to `ContentApiModel`

`ContentModelMapperBase`, `DefaultContentModelMapper` and `IContentModelMapper` were removed. `DefaultContentConverter` and `IContentConverter`, which serves the same purpose, are introduced instead in an internal namespace.

`DefaultPropertyModelConverter` and `IPropertyModelConverter` were removed. `IPropertyConverter`, `IPropertyConverterProvider` and `IPropertyConverterResolver` are introduced to customize the content's properties converting flow. See [Add custom content property converter in Content Delivery API](docId\:rQjpokYPn4MRSi50uxGck).

`ContentLoaderService`, `UrlResolverService`, and `ContentConvertingService` were moved to an internal namespace.

To customize the content that is returned, use `IContentFilter` and `IContentModelFilter` instead. Also, see [Customize data returned to clients](docId\:G0-aJ6fe4B2u8u7UHsx1L).

### Customize how data is returned to the client

`ContentResultService`, `IContentApiSerializer` and `IJsonSerializerConfiguration` were removed.

`IContentModelFilter` and `IContentFilter`, which serves the same purpose, were made public. See [Customize data returned to clients](docId\:G0-aJ6fe4B2u8u7UHsx1L).

### Friendly Url

`ContentAPIRouteService` was moved to an internal namespace.

## Classes made internal

In addition to the classes mentioned above, the following classes were made internal:

- `ReflectionService`
- `ContentApiModelFilter` (from preview to internal)
- `ContentFilter` (from preview to internal)
- `IContentConverterResolver`
- `IExcludeFromModelTypeRegistration`
- `IPropertyConverterResolver`
- `ISiteDefinitionConverter`
- `IXHtmlStringPropertyRenderer`
- `IContentModelReferenceConverter`
- `InitializationService`
- `ContentApiRequiredRoleFilter`
- `ContentAPISiteFilter`
- `IContentApiRequiredRoleFilter`

## Authorization

`ISecurityPrincipal` was removed and `ContentApiAuthorizationService` is moved to an internal namespace. These classes were previously used to customize authorization.

In version 3, the `EPiServer.ContentDeliveryApi.OAuth` package was replaced by `EPiServer.OpenIDConnect`. See [API authentication](docId\:GcwKCbUQUXLkDILm5DQmW).

Following security-related classes and interfaces were removed:

- `IContentApiSiteFilter`
- `ContentApiAuthorizationAttribute`
- `ContentApiCorsAttribute`
- `CorsOptionsActionFilter`