Configure Content Delivery API

10 min

You can configure the Optimizely Content Delivery API by working with an instance of ContentApiOptions.

ContentApiOptions

You can configure ContentApiOptions in ConfigureServices in startup.cs when you enable the API:

services.AddContentDeliveryApi(options => {
  // Access the options here
});

You can also configure the ContentApiOptions after you enable the API:

services.Configure<ContentDeliveryApiOptions>(options => {
  // Access the options here
});

RichText

You can configure how RichText or XhtmlString properties should be delivered by configuring ContentApiOptions.RichTextFormat. The options are:

/// <summary>
/// Specifies how rich text properties should be formatted.
/// </summary>
public enum RichTextFormat {
  /// <summary>
  /// Specifies that the data format should be a html based string
  /// </summary>
  Html,
  /// <summary>
  /// Specifies that the data format should be in a structured format.
  /// </summary>
  Structured,
  /// <summary>
  /// Specifies that the data should be returned both as html and in a structured format.
  /// </summary>
  HtmlAndStructured
}

The structured format is based on Slate. There are two types of nodes: an element with a type property specifying which type of element it is, and a children property of sub-nodes. The other node type is text, which contains the actual text and optionally formatting of the text. A text node is a leaf node; it has no children. The following example shows a paragraph node with a heading and some text:

{
  "type": "paragraph",
  "children": [
    {
      "type": "heading-one",
      "children": [
        {
          "text": "Alloy partner",
          "italic": true
        }
      ]
    },
    {
      "text": "Work with an Alloy Technology partner to define the scale of your organization's needs and find the best fit with Alloy Plan."
    }
  ]
}

ContentSearchApiOptions

You can configure ContentSearchApiOptions in ConfigureServices in startup.cs when you enable the API:

services.AddContentSearchApi(options => {
  // Access the options here
});

You can also configure the ContentSearchApiOptions after you enable the API:

services.Configure<ContentSearchApiOptions>(options => {
  // Access the options here
});

Security

To access secured content through the API, authenticate the request using OpenID Connect and Bearer Tokens (JWT). See API authenticationAPI authentication for instructions on how to enable it.

The APIs use the configured default authentication scheme. See Microsoft's documentation about authentication schemes.

When you configure the APIs, the authentication scheme is the first parameter to use, as shown in the following example:

public void ConfigureServices(IServiceCollection services) {
  // Use overload without the scheme parameter to use the default scheme.
  services.AddContentDeliveryApi("MyScheme", options => {
    // Access options here
  });
}

📘 Note All content having read access for the 'Everyone' role is available through the API by default. You can change this in the following ways:

Configure AllowedScopes in ContentDeliverApiOptions. Then requests need to have any of these scopes to call the API.

Configure RequiredRole in ContentDeliveryApiOptions. Then assign these roles read access to each content item that should be available in the API.

CORS

APIs use the default configured CORS policy. See Microsoft's documentation how to configure CORS.

You can configure each API to use a specific CORS policy in ConfigureServices in startup.cs:

services.AddContentDeliveryApi(options => {
  // To use a specific policy, specify the name of the policy.
  // To use the default policy, leave empty.
  options.CorsPolicyName = "MyPolicyName";
});

You can add a named policy in ConfigureServices in startup.cs:

services.AddCors(options => {
  options.AddPolicy("MyPolicyName", b => b
    .WithOrigins(new[] { "http://localhost:8080" })
    .WithExposedContentDeliveryApiHeaders()
    .AllowAnyHeader()
    .AllowAnyMethod()
    .AllowCredentials());
});

You can also add a default policy directly in Configure in startup.cs:

app.UseCors(b => b
  .WithOrigins(new[] { "http://localhost:8080" })
  .WithExposedContentDeliveryApiHeaders()
  .AllowAnyHeader()
  .AllowAnyMethod()
  .AllowCredentials());

WithExposedContentDeliveryApiHeaders() enables Content Delivery-specific headers. If not configured, these headers are not served if the call is a cross-origin request.

The following method configures CORS automatically based on the host configured on the current SiteDefinition:

services.AddContentDeliveryApiSiteBasedCors();

Or:

services
  .AddContentDeliveryApi()
  .WithSiteBasedCors();