Installation and configuration

Installation

Prerequisites

Install Optimizely updates through the NuGet Package Manager in Visual Studio.

Installing the Service API components

Open Visual Studio and follow the steps below.

1. Set the target framework for your project to .NET 5.0 or higher by right-clicking on the project and choosing Properties.
2. Select Tools > NuGet Package Manager > Manage NuGet packages for Solution... (or right-click on the solution References and select there).
3. Click Settings to create a source pointing to the Optimizely NuGet feed.
4. Open the Online section and select the source you just created.
5. Install EPiServer.ServiceApi or EPiServer.ServiceApi.Commerce.
6. Install EPiServer.OpenIDConnect to allow token authentication.

📘

Note

ServiceAPI suppressed cookie authentication in the default configuration.

Configuring authentication

See API authentication for more detailed information. The following example shows how to configure open connect for Service API.

services.AddOpenIDConnect<SiteUser>(options =>
                {
                    //options.RequireHttps = !_webHostingEnvironment.IsDevelopment();
                    var application = new OpenIDConnectApplication()
                    {
                        ClientId = "postman-client",
                        ClientSecret = "postman",
                        Scopes =
                        {
                            ContentDeliveryApiOptionsDefaults.Scope,
                            ContentManagementApiOptionsDefaults.Scope,
                            ContentDefinitionsApiOptionsDefaults.Scope,
                            ServiceApiOptionsDefaults.Scope
                        }
                    };
    
                    // Using Postman for testing purpose.
                    // The authorization code is sent to postman after successful authentication.
                    application.RedirectUris.Add(new Uri("https://oauth.pstmn.io/v1/callback"));
                    options.Applications.Add(application);
                    options.AllowResourceOwnerPasswordFlow = true;
                });
                
                services.AddOpenIDConnectUI();

Disable SSL requirement for request

By default, Service API requires secure connections both for authentication and for API calls. You can disable this with an app setting, for example, for a debug configuration in development.

{
        "EPiServer" : {
            "ServiceApi" : {
                "RequireSsl":false
             }
        }
    }

    public void ConfigureServices(IServiceCollection services)
    {
        services.Configure<ServiceApiOptions>(x => x.RequireSsl = false);
    }

📘

Note

Live sites should not disable SSL.

Authentication tokens

To use any EPiServer.ServiceApi RESTful method, you must obtain an "OAuth 2 Bearer Token" to send with the request.

using (var client = new HttpClient())
      {
        client.BaseAddress = new Uri("https://mysite.com/");
        var fields = new Dictionary<string, string>
          {
            { "grant_type", "client_credentials" },
            { "client_id", username },
            { "client_secret", password },
            { "scope", ServiceApiOptionsDefaults.Scope}
          };
        var response = client.PostAsync("/api/episerver/connect/token", new FormUrlEncodedContent(fields)).Result;
        if (response.StatusCode == HttpStatusCode.OK)
          {
            var content = response.Content.ReadAsStringAsync().Result;
            var token = JObject.Parse(content).GetValue("access_token");
          }
      }         
    
    POST /episerverapi/token HTTP/1.1
    Host: mysite.com
    User-Agent: Mozilla/5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1667.0 Safari/537.36
    Content-Type: application/x-www-form-urlencoded;charset=UTF-8
    Content-Length: 29
    Accept-Encoding: gzip
    grant_type=password
    username=test
    password=test

HTTP/1.1 200 OK
    Status: 200 OK
    Content-Type: application/json; charset=utf-8
    ...
    Content-Encoding: gzip
    Content-Length: 140
    {"token_type":"bearer","access_token":"AAAA%2FAAA%3DAAAAAAAA"}

Sending request with tokens

using (var client = new HttpClient())
      {
        client.BaseAddress = new Uri("https://mysite.com/");
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.ToString());
        var content = new MultipartFormDataContent();
        var filestream = new FileStream(path, FileMode.Open);
        content.Add(new StreamContent(filestream), "file", "Catalog.zip");
        var response = client.PostAsync("/episerverapi/commerce/import/catalog", content).Result;
        if (response.StatusCode == HttpStatusCode.OK)
          {
            var returnString = response.Content.ReadAsStringAsync().Result;
            returnString = returnString.Replace("\"", "");
            Guid taskId = Guid.Empty;
            Guid.TryParse(returnString, out taskId);
          }
      }

Strongly typed catalog content types

Strongly typed catalog content types must be present in the context of a ServiceAPI site. If you install ServiceAPI to an existing website, this is solved automatically. However, if you install ServiceAPI as a standalone application, you must deploy the assembly that contains strongly typed catalog content types (and any dependencies of your assembly) to the ServiceAPI bin folder.

Troubleshooting

The following issues may arise when you set up the Service API.

• Make sure there is a valid certificate on the server from a trusted certificate authority for the site.
• Make sure all Service API requests are HTTPS.

There is no rate limit set for the Service API.

See also Service API REST API reference.

Permissions for Functions

You can configure the read and write functions of the Service API in the Permissions for Functions area.

1. Navigate to Admin > Access Rights > Permissions for Functions.
2. Under EPiServerServiceApi, select ReadAccess or WriteAccess, depending on the desired permission.
   For instance, you may want to give access for reading or updating the catalog via endpoint, such as the following endpoints:
   /episerverapi/commerce/export/catalog/
   /episerverapi/commerce/import/catalog/
3. Add the User or the ClientId value that has been set up in the middleware configuration of the ServiceAPI.