Loading...
Area: Episerver B2B Commerce

Admin API architecture

Recommended reading 

Synopsis

The Epi B2B 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 API's allow third party applications (client or partner) to read and write administration data without the admin console.

Note: Access Swagger to view and test endpoints by using "your website URL/swagger".

Topics

  • Admin API Architecture
  • Consuming the Admin API
  • OData Entities
  • Admin API Endpoints

Admin API Architecture

Overview

Epi B2B 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, Epi B2B 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.

Epi B2B 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.

Consuming 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.

Body (x-www-form-urlencoded)

Sample values

grant_type

password

username

admin_[username]

password

P@ssw0rd

scope

iscapi

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 allows you to 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.

Body (x-www-form-urlencoded)

Sample values

grant_type

password

username

admin_[username]

password

P@ssw0rd

scope

isc_admin_api offline_access

 

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 please visit the OData URI conventions here http://www.odata.org/documentation/odata-version-2-0/uri-conventions/.

Epi B2B 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 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)

Returning a child collection from the Admin API

Out of the box OData only supports the entity and no child collections. So Epi B2B 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

Updating entities using the Admin API

All of the entities within Epi B2B 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. Epi B2B Commerce replaced the Insite.Model library with the Insite.Data.Entities library. Eventually all entities will be split into the modules.

Epi B2B 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.

Swagger

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 of B2B Commerce Help.

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/

HTTP Verb

URL

Description

GET

entity

Retrieves all of the the objects

POST

entity

Creates a new object

GET

entity({id})

Retrieves the object by Unique Id

PUT

entity({id})

Update or create an object by Unique Id

DELETE

entity({id})

Deletes an object by Unique Id

PATCH

entity({id})

Updates properties on an existing object by Unique Id

GET

entity/Default.Default()

Returns a new instance of that object with all of the default values

GET

entity({key})/child({childKey})

Retrieves a single child by Unique Id relative to the parent object

GET

entity({key})/customproperties({custompropertyKey})

Retrieves the value of a single custom property on an object

Related Articles:

Do you find this information helpful? Please log in to provide feedback.

Last updated: Dec 11, 2020

Recommended reading