Configured Commerce Admin API architecture

The Optimizely Configured Commerce Admin Console delivers a modularized software architecture for improved performance, as well as easier upgrades and integration. Each module has a RESTful interface for communicating between modules and the UI. The RESTful APIs allow third-party applications (client or partner) to read and write administration data without the admin console.

📘

Note

Access the OpenAPI Specification (aka Swagger) to view and test endpoints by using [YOUR_WEBSITE_URL]/swagger.

Admin API Architecture

Configured Commerce uses Entity Framework Code First version 6. In general, the entity framework autogenerates OData controllers. Using a custom-built OData T4 template, Configured Commerce autogenerates the OData controllers based on the entities available.

The ODataControllers.tt T4 template is maintained as base code in the Insite.Admin library. To extend this functionality, you should implement a custom T4 template independently. You cannot extend the existing T4 template.

Configured Commerce supports one level deep of any child navigation property. For example, websites have countries as a child collection. Entities can have properties that are archivable, which means they have an active or deactivated state. Deleting items archives that entity. Archiving is used generically across entities. Archiving an entity is synonymous with the archiving property of that entity type. For example:

• Setting the DateTime deactivate property to today's date archives the product entity.
• Setting the Boolean archive property to False archives the customer entity.

You can use the Admin API to retrieve archived entities by appending the archivedFilter=1 OData query.

The following example retrieves archived customers:

/api/v1/admin/customers?&archiveFilter=1

Querying, updating, deleting is all in the Controllers/Odata folder.

Consume the Admin API

Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs. You can also use tools such as Curl or Fiddler.

You can download the Postman collection with the requests for this process.

To consume storefront REST APIs, create a POST request with URL: [http or https]://[YOUR_WEBS-TE_URL]/identity/connect/token

Select Authorization > Basic Auth. Enter the following username and password:

• Username – isc
• Password – 009AC476-B28E-4E33-8BAE-B5F103A142BC

The image below shows an example with the website URL as localhost:3010.

Go to Body, and choose x-www-form-urlencoded. Fill in the following information:

Whereas the Admin API requires different scope and user credentials with access to the Admin Console, the clientid:secret are different than the website access. The offline\_access scope returns a refresh token along with the bearer token. The bearer token expires after 15 minutes (900 seconds), so the refresh token allows you to get a new bearer token without specifying the username and password. The refresh token is used in the Admin Console, and the JavaScript automatically gets the new bearer token. The refresh token is stored in localstorage. It is only used when requesting a new bearer token.

To consume Admin REST API, create a POST request with URL: [http or https]://[YOUR_WEBSITE_URL]/identity/connect/token

Select Authorization > Basic Auth. Use the following username and password:

• Username – isc_admin
• Password – F684FC94-B3BE-4BC7-B924-636561177C8F

The image below shows an example with the website URL as localhost:3010.

Go to Body, and choose x-www-form-urlencoded. Fill in the following information:

If the bearer token has expired, any call made to the Admin API receives a 401 Unauthorized response. For example, this happens if you make a call to http://42.local.com/api/v1/admin/websites using an outdated Authorization bearer token.

Because OData exposes the API, you can apply query string parameters using the OData standards, such as count to retrieve a certain number of results.

For more information regarding OData parameters please visit the OData URI conventions website.

Configured Commerce returns a maximum of 100 results in a Admin API request, and the OData.NextLink requests the next set of results. This OData.NextLink JSON value is the name of the API endpoint plus the query string with skip=100.

Return a single object from the Admin API

Unlike the website API (the Storefront API), the Admin API uses OData syntax.

The following example shows how to retrieve a single product using the Storefront API and the Admin API:

Storefront API return a single object syntax – /api/v1/products/f88d5c07-eb72-42eb-ab36-a5d201168a49

Admin API return a single object syntax – /api/v1/admin/products(f88d5c07-eb72-42eb-ab36-a5d201168a49)

Return a child collection from the Admin API

Because OData only supports the entity and no child collections, Configured Commerce supports one level deep child collections. You can retrieve child collections on a RESTful JSON result in two ways:

1. Use the expand parameter for the query string.
2. Use the name of the child entity after the slash.

The following example shows how to retrieve a child collection of a website using the Admin API:

Use the expand parameter for the query string – /api/v1/websites(d24h5c07-eb72-42eb-ab36-a5d201168jh5)?$expand=countries

Use the name of the child entity after the slash – /api/v1/websites(d24h5c07-eb72-42eb-ab36-a5d201168jh5)/countries

Update entities using the Admin API

All entities within Configured Commerce contain a Patch endpoint for the Admin API.

The following is an example of how to update a specific website to make it inactive.

{
  	"isActive": false
}

In the body of the request, set the property and value using JSON notation. Additionally, the request header must contain the authentication bearer token.

OData Entities

The Insite.Data.Entities library contains the models as simple objects. There is no business logic in the entity objects. Configured Commerce replaced the Insite.Model library with the Insite.Data.Entities library and splits all entities into the modules.

Configured Commerce follows the UnitOfWork pattern, so there is a data provider implementation for Entity Framework. Consuming the data has not changed. You can use a repository from Unit of work to retrieve an IQuerable object.

All entities have the OData RESTful service available. The T4 template generates the classes and defines them as Partial classes for extensibility. You can make any additions or extensions to the auto generated controllers using Partial classes.

The Admin API respects any security constraints, including authenticated user.

Swagger

You can view and interact with both the Storefront and Admin API endpoints via Swagger. Configured Commerce Help contains links for both the Storefront API and Admin API.

> 📘 Note

You can also view the available endpoints by scrolling in the left navigation to Storefront API V1, Storefront API V2, or Admin API V1.

Admin API Endpoints

The following definitions describe the API endpoints for data-level objects, also known as Admin objects.

Generic endpoint definitions

Url Prefix: /api/v1/admin/