Applies to versions: 2.x

Other versions:

ARCHIVED This content is retired and no longer maintained. See the version selector for other versions of this topic.

Configuration

ContentApiOptions

To change the default values of ContentApiOptions:

Create a new class inheriting IConfigurableModule and give it a name, for example: ExtendedContentApiCmsInitialization.
Decorate the class with [ModuleDependency(typeof(ContentApiCmsInitialization))]
Within the ConfigureContainer function, change the default values for ContentApiOptions.

Config sample

[ModuleDependency(typeof(ContentApiCmsInitialization))]
public class ExtendedContentApiCmsInitialization : IConfigurableModule
  {
    public void Initialize(InitializationEngine context)
      {
      }
    public void Uninitialize(InitializationEngine context)
      {
      }
    public void ConfigureContainer(ServiceConfigurationContext context)
      {
        context.Services.Configure<ContentApiConfiguration>(config =>
          {
            config.Default()
            .SetMinimumRoles("HeadlessAPI")
            .SetRequiredRole("HeadlessAPI")
            .SetSiteDefinitionApiEnabled(true)
            .SetMultiSiteFilteringEnabled(false);
          });
      }
  }

If the site only installs EPiServer.ContentDeliveryApi.Search, the type of ModuleDependency should be changed to ContentApiSearchInitialization. See the section below for more details.

ContentSearchApiOptions

To change the default values of ContentSearchApiOptions:

Create a new class inheriting IConfigurableModule and give it a name, for example: ExtendedContentApiSearchInitialization.
Decorate the class with [ModuleDependency(typeof(ContentApiSearchInitialization))]
Within the ConfigureContainer function, change the default values for ContentSearchApiOptions.

Config Sample

[ModuleDependency(typeof(ContentApiSearchInitialization))]
public class ExtendedContentApiSearchInitialization : IConfigurableModule
  {
    public void Initialize(InitializationEngine context)
      {
      }
    public void Uninitialize(InitializationEngine context)
      {
      }
    public void ConfigureContainer(ServiceConfigurationContext context)
      {
        context.Services.Configure<ContentApiSearchConfiguration>(config =>
          {
            config.Default()
            .SetMaximumSearchResults(200)
            .SetSearchCacheDuration(TimeSpan.FromMinutes(60));
          });
      }
  }

Map RequiredRole to group roles

By default, Content Delivery API sets the value contentapiread for RequiredRole in ContentApiOptions, and maps it to the group roles: WebEditors, Administrators, and WebAdmins. Content Delivery API lets you change default values for mapped group roles by adding a virtual role in web.config.

Config sample

<virtualRoles addClaims="true"> 
  <providers> 
    <add name="contentapiread" 
         type="EPiServer.Security.MappedRole, EPiServer.Framework"
         roles="YourGroup01, YourGroup02, WebEditors" 
         mode="Any" />
  </providers> 
</virtualRoles>

Note: The value of the group name must be the same as ContentApiOption.RequiredRole. For the first version, you have to manually create contentapiread and assign the privileges to the role. From version 2.1.0, the initialization service does it automatically.

Default HttpConfiguration

To enable web api, EPiServer.ContentDeliveryApi.Cms and EPiServer.ContentDelivery.Search need to set up some default values for HttpConfiguration and most importantly, call (HttpConfiguration)config.MapHttpAttributeRoutes(). If the site has done this before, you can disable those setups by adding theses two lines in appSettings.

Disable settings from ContentDeliveryApi.Cms:

<add key="episerver:contentdelivery:maphttpattributeroutes" value="false" />

Disable settings from ContentDeliveryApi.Search:

<add key="episerver:contentdeliverysearch:maphttpattributeroutes" value="false" />

Note: If the site installs both cms and search packages, and does not use any kind of service API, one of two lines above should be added to appSettings. This prevents (HttpConfiguration)config.MapHttpAttributeRoutes() from being called twice, which otherwise causes an exception.

OAuth configuration

If you need to use the EPiServer.ContentDeliveryApi.OAuth package, add this line in the Configuration function in Startup.cs, preferably at the end of the function.

app.UseContentApiIdentityOAuthAuthorization<ApplicationUserManager<ApplicationUser>, ApplicationUser>(new ContentApiOAuthOptions()
{
  RequireSsl = false,
  AccessTokenExpireTimeSpan = TimeSpan.FromMinutes(41),
  RefreshTokenExpireTimeSpan = TimeSpan.FromDays(14),
  TokenEndpointPath = "your path" // by default, if not configured, its value is /api/episerver/auth/token
});

You can use the default implementation of CMS UI for both ApplicationUserManager and ApplicationUser. You can see the sample configuration in the Startup.cs in the Alloy sample site for Content Delivery API.

Do you find this information helpful? Please log in to provide feedback.

Last updated: Mar 02, 2022