Loading...

Last updated: Aug 31 2018

Area: Episerver CMS Applies to versions: 1.0.0 and 1.0.1

Installing Content Delivery API

The Content Delivery API is installed using the NuGet package: EPiServer.ContentDeliveryApi.

Installation

After installing EPiServer.ContentDeliveryApi, download the Infrastructure folder and replace the files in your solution with the downloaded files: SiteInitialization.cs, StructureMapDependencyScope.cs, StructureMapResolver.cs, and StructureMapDependencyResolver.cs.

Note: Those files' namespaces should be changed in line with your solution.

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 });

Next, create a role named contentapiread in admin view. Give this role access right to all content that should be exposed through the Content Delivery API. If using our additional files mentioned above, request identity should be assigned to the role contentapiread because contentapiread is set as minimumroles. See Configuration section for more details.

Note that the user identity used for ContentDelivery should have the access right to the contents that it requests.

Configuration

In this section

The Content Delivery API can be configured by working with an instance of ContentApiOptions, allowing the following elements of the API to be configured:

Minimum roles

This defines a group of comma-separated roles that can use ContentDelivery. The request identity must belong to one of those roles defined in MinimumRole to be able to access API. If MinimumRole is set as null or empty, there is no restriction on API users. By default, MinimumRole is contentapiread and it can be changed in SiteInitialization.cs.

Required role

By default, the ContentDelivery can only access content that has been granted an explicit Required Role via the Episerver Access Rights system. This security feature enables developers to selectively expose certain content for ContentDelivery, while leaving other content for internal use. By default, the Required Role should have the value of contentapiread, and this can be changed in SiteInitialization.cs.

Note that after the Required Role is granted access right to content in admin view, for Content Delivery Search, Episerver Find should re-index the site to get the latest update.

Like mentioned above, in addition to the Required Role, content is still filtered based on the access rights of requesting identity. For example, if a page is only accessible by Administrators, request identities other than Administrator cannot access the content via ContentDelivery, even if the Required Role is granted Read permission on the page.

Note: The Content Delivery API does not filter out content in ExpandedValue properties based on the Required Role. If a content item (like an Image or Block) is referenced in a Content Reference or Content Area, it will be exposed in the Content Delivery API when the property is expanded. This is by design, to ensure the API is convenient to navigate related content.

Multi-site filtering

By default, only information and content from the current Episerver site is returned in requests to the ContentDelivery. The current site is detected based on the request context, configured sites and their domains in the Episerver admin view.

This feature ensures proper separation between sites in a multi-site configuration and extends across the Content Delivery API, the Content Search API, and the Site Definition API. In order to disable this option, set the MultiSiteFilteringEnabled property to false.

Note: The Content Delivery API does not filter out content in ExpandedValue properties based on Multi-site Filtering. If a content item (like an Image or Block) is referenced in a Content Reference or Content Area, it will be exposed in the Content Delivery API when the property is expanded. This is by design, to ensure the API is convenient to navigate related content.

Search cache duration

By default, the Content Search API caches all requests to Episerver Find for 30 minutes. Using the SearchCacheDuration property, this TimeSpan can be customized to limit how long results will be cached. In order to disable caching, set the property to TimeSpan.Zero. This value can be changed in SiteInitialization.cs.

Maximum search results

By default, the Content Search API returns a maximum of 100 results in a given request. If the search request is passed with a top parameter larger than this maximum, a 400 Bad Request status code is returned. The MaximumSearchResults parameter allows this limit to be decreased, or increased, and developers should be aware of performance considerations when adjusting this value. This value can be changed in SiteInitialization.cs.


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/