Loading...

Last updated: Oct 30 2018

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

The OAuth configuration should be the same as version 1.0.1, in case that you need to use the EPiServer.ContentDeliveryApi.OAuth package. 


Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/