APIs Admin API

Configured Commerce Admin API Overview

• The Optimizely Configured Commerce Admin Console has a modularized software architecture for performance, upgrades, and integration.
• Each module communicates using RESTful APIs enabling third-party applications to interact with administration data.
• You can view and test endpoints using the OpenAPI Specification (aka Swagger) at [YOUR_WEBSITE_URL]/swagger.

Admin API Architecture Details

• Entity Framework Code First version 6 autogenerates OData controllers for Configured Commerce.
• A custom-built OData T4 template generates these controllers based on available entities.
• The ODataControllers.tt T4 template is maintained in the Insite.Admin library.
• Configured Commerce supports one level deep of any child navigation property.
• Entities can have properties marked as archivable with an active or deactivated state.
• Deleting items archives the entity.
• Archiving is used generically across entities.
• To retrieve archived entities, use the archivedFilter=1 OData query.
• For example, to retrieve archived customers: /api/v1/admin/customers?&archiveFilter=1.

Consuming the Admin API

• Postman simplifies API development and helps manage the API lifecycle.
• You can use tools like Curl or Fiddler to consume the Admin API.
• To consume storefront REST APIs, create a POST request at: [http or https]://[YOUR_WEBS-TE_URL]/identity/connect/token.
• Use Basic Auth with username 'isc' and password '009AC476-B28E-4E33-8BAE-B5F103A142BC'.
• In the Body, select x-www-form-urlencoded.
• Fill in the required information:
  • grant_type: password
  • username: [web user name (e.g., basicuser)]
  • password: [web user password (e.g., Password1)]
  • scope: iscapi offline_access

Admin API Authentication

• The Admin API uses different scope and user credentials compared to 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).
• The refresh token allows you to get a new bearer token without specifying the username and password.
• The refresh token is stored in local storage and used only when requesting a new bearer token.
• To consume Admin REST API, create a POST request at: [http or https]://[YOUR_WEBSITE_URL]/identity/connect/token.
• Use Basic Auth with username 'isc_admin' and password 'F684FC94-B3BE-4BC7-B924-636561177C8F'.
• In the Body, select x-www-form-urlencoded.
• Fill in the required information:
  • grant_type: password
  • username: admin_[console user name] (e.g., admin)
  • password: [console user password (e.g., Password1)]
  • scope: isc_admin_api offline_access

Admin API Response Handling

• If the bearer token is expired, any call to the Admin API will receive a 401 Unauthorized response.
• You can apply OData query string parameters to refine requests using OData standards.
• Configured Commerce returns a maximum of 100 results per request.
• OData.NextLink provides the next set of results.

Admin API and OData

• Configured Commerce uses OData syntax for the Admin API, unlike the Storefront API.
• For example, to retrieve a single product:
  • Storefront API: /api/v1/products/f88d5c07-eb72-42eb-ab36-a5d201168a49
  • Admin API: /api/v1/admin/products(f88d5c07-eb72-42eb-ab36-a5d201168a49)

Child Collection Retrieval

• Configured Commerce supports one level deep of child collections using OData.
• You can retrieve child collections using two methods:
  • Using the expand parameter in the query string (e.g. /api/v1/websites(d24h5c07-eb72-42eb-ab36-a5d201168jh5)?$expand=countries)
  • Using the child entity name after the slash (e.g. /api/v1/websites(d24h5c07-eb72-42eb-ab36-a5d201168jh5)/countries)

Updating Entities

• All entities in Configured Commerce have a Patch endpoint for the Admin API.
• To update an entity, include the new property and value in the JSON body and the authentication bearer token in the request header.

Entities and Data Provider

• The Insite.Data.Entities library contains the model objects without business logic.
• Configured Commerce uses the UnitOfWork pattern and a data provider implementation for Entity Framework.
• You can use repositories from Unit of work to retrieve an IQueryable object.
• All entities have an OData RESTful service.
• The T4 template generates the classes and enables extensibility through partial classes.

Swagger

• Use Swagger to view and interact with the Storefront and Admin API endpoints.
• You can access the endpoints in the left navigation (Storefront API V1, Storefront API V2, or Admin API V1).

Admin API Endpoints

• Url Prefix: /api/v1/admin/
• The table below summarizes the generic endpoint definitions. | HTTP Verb | URL | Description | |-------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------| | GET | entity | Retrieves all the objects | | POST | entity | Creates a new object. Use entity/Default.Default() to get an instance with default values. | | GET | entity({id}) | Retrieves the object by the specified ID. | | PUT | entity({id}) | Update or create an object by the specified ID. | | DELETE | entity({id}) | Deletes an object by the specified ID. | | PATCH | entity({id}) | Updates properties on an existing object by the specified ID. | | GET | entity({key})/child({childKey}) | Retrieves a single child by its ID relative to the parent object. | | GET | entity({key})/customproperties({custompropertyKey}) | Retrieves the value of a single custom property on an object. |

Explore the modular architecture and RESTful APIs of the Optimizely Configured Commerce Admin Console. This quiz covers various aspects including OData controllers and archivable entities, offering insights into effective third-party application integration.