Loading...
Area: Content Delivery API
Applies to versions: 2 and higher
Other versions:

Configuration

The Content Delivery API can be configured by working with an instance of ContentApiOptions. This topic mainly presents how to customize the default configurations for ContentDeliveryApi.

In this topic

ContentApiOptions

To change the default values of ContentApiOptions:

  • Create a new class inhereting 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 inherting 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, ContentDeliveryApi sets the value "contentapiread" for RequiredRole in ContentApiOptions, and maps it to the group roles: WebEditors, Administrators, and WebAdmins. ContentDeliveryApi 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. But for version 2.1.0, our initialization service will do 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 ContentDeliverApi.Cms:
    <add key="episerver:contentdelivery:maphttpattributeroutes" value="false" />
  • Disable settings from ContentDeliverApi.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

In case that 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
});

Last updated: Oct 30, 2018