APIs - Admin API.pdf

Configured Commerce Admin API architecture Overview of the Admin API architecture for Optimizely Configured Commerce. 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...

Configured Commerce Admin API architecture Overview of the Admin API architecture for Optimizely Configured Commerce. 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: Key Value grant_type password [web user name] username for example: basicuser [web user password] password for example: Password1 scope iscapi offline_access 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: Key Value grant_type password username admin_[console user name] for example: admin [console user password] password for example: Password1 scope isc_admin_api offline_access 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. JSON { "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/ HTTP URL Description Verb Retrieves all of the the GET entity objects POST entity Creates a new object Retrieves the object by GET entity({id}) Unique Id Update or create an PUT entity({id}) object by Unique Id DELET Deletes an object by entity({id}) E Unique Id Updates properties on PATCH entity({id}) an existing object by Unique Id Returns a new instance GET entity/Default.Default() of that object with all of the default values Retrieves a single child GET entity({key})/child({childKey}) by Unique Id relative to the parent object Retrieves the value of a entity({key})/customproperties({custompropert GET single custom property yKey}) on an object