Installation and configuration
This section describes how to install and configure the Optimizely Service API, a service layer used for integration of Optimizely Commerce with external systems, such as PIM, DAM and ERPs.
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.
- Set the target framework for your project to .NET 5.0 or higher by right-clicking on the project and choosing Properties.
- Select Tools > NuGet Package Manager > Manage NuGet packages for Solution... (or right-click on the solution References and select there).
- Click Settings to create a source pointing to the Optimizely NuGet feed.
- Open the Online section and select the source you just created.
- Install EPiServer.ServiceApi or EPiServer.ServiceApi.Commerce.
- Install EPiServer.OpenConnect.UI to allow token authentication.
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 }
};
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.
Updated 27 days ago