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 will have a RESTful interface for communicating between modules and the UI. The RESTful API's allow third parties applications (client or partner) to read and write administration data without the admin console.

Admin API architecture

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

The ODataControllers.tt T4 template is maintained as base code in the Insite.Admin library. If developers would like to extend this functionality it is recommended to implement a custom T4 template independently. Developers 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. When items are deleted it will ultimately archive that entity. Archiving is used generically across entities. When an entity is archived, the archiving action is synonymous with the archiving property of that entity type.

For example, the product entity is archived by setting the DateTime deactivate property to today's date.

For example, the customer entity is archived by setting the Boolean archive property to false.

Using the Admin API developers can retrieve archived entities by appending the archivedFilter=1 OData query.

The following example will retrieve archived customers:

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

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

Consume the admin API

PostMan is a Google Chrome extension that is a great tool for testing the API. Other tools such as Curl and Fiddler can be used as well.

Get a bearer token from the website. /identity/connect/token. Pass in an authorization header Basic Base64 encoded value of ClientID:Secret.

Whereas the Admin API requires different scope and user credentials with access to the Admin Console. Same URL. The clientid:secret are different than the website access. The offline_access scope will return a refresh token along with the bearer token. The bearer token expires after 15 (900) minutes, so the refresh token lets you get a new bearer token without specifying the username and password. The refresh token is used in the admin console, the JavaScript will automatically get the new bearer token. The refresh token is stored in localstorage. It is not used in requests it is only used when a new bearer token is requested.

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

The API is exposed via OData which means developers 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 visit the OData URI conventions here URI Conventions (OData Version 2.0).

Configured Commerce is configured to return a maximum of 100 results in a request to the Admin API. Because of this, the OData.NextLink is configured to request the next set of results. This OData.NextLink JSON value is set to the name of the API endpoint plus the query string with skip=100.

Returning a single object from the Admin API

Unlike the website API, also known as the Commerce 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:

/api/v1/products/f88d5c07-eb72-42eb-ab36-a5d201168a49

Storefront API return a single object syntax:

Admin API return a single object syntax:

/api/v1/admin/products(f88d5c07-eb72-42eb-ab36-a5d201168a49)

Return a child collection from the admin API

Out of the box OData only supports the entity and no child collections. Configured Commerce has been built to support one level deep child collections. There are two ways to retrieve child collections on a RESTful JSON result.

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 of the entities within Configured Commerce will contain a Patch endpoint for the Admin API.

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

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 models are located in the Insite.Data.Entities library and have been rewritten as simple objects. There is no business logic in the entity objects. Configured Commerce now replaced the Insite.Model library with the Insite.Data.Entities library. Eventually all entities will be split into the modules.

Configured Commerce follows the UnitOfWork pattern, so there is a data provider implementation for Entity Framework. Consuming the data hasn't changed. Developers will use a repository from Unit of work to retrieve an IQuerable object.

All of the entities have the OData RESTful service available. The classes generated by the built in T4 template defines them as Partial classes for extensibility. This means that any additions or extensions to the auto generated controllers can be done using Partial classes.

Any security constraints configured, including authenticated user, will be respected on all calls to the Admin API.

Developers can view and interact with both the Storefront and Admin API endpoints via Swagger. Links for both the Storefront API and Admin API are provided via the top level navigation within the Developer Portal

Admin API endpoints

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

Url Prefix: /api/v1/admin/