About SimpleAPI

SimpleAPI is a CloudBlue Commerce component that introduces an easy-to-use REST API that can be used by resellers to integrate their own IT systems, without requiring them to have extensive knowledge of technical CloudBlue Commerce platform concepts.

SimpleAPI is based on the Open API Specification, which allows developers to quickly generate code samples, test their integration scenarios, and deploy their integration.

The SimpleAPI component includes additional modules, such as a mock version that simulates API allowing API users to test their code without affecting the platform, as well as an application that automates the process by which resellers gain access to the API.

With SimpleAPI, the following scenarios become available:

Retrieving the product catalog
Creating and updating customer accounts
Placing sales, change, renewal, and cancellation orders
Retrieving orders and their details
Listing subscriptions and their details
Listing and scheduling rated data reports

Authenticated Access

Resellers can choose two separate methods of authenticating. Once authenticated, all further API requests are made using the Bearer Authentication. If Azure API Management (APIM) is used, a valid subscription will need to be sent as well.

Basic Authentication

This method is native to SimpleAPI and allows a reseller request an access token using basic authentication. This method requires only that the reseller has a staff member with full admin privileges and leverages UI sessions to generate a token for the API user.

OAuth 2 Authentication

This method requires OAuth 2 to have been configured for CloudBlue Commerce and that the staff member used has the correct Allowed Operations configured. With the SimpleAPI Onboarding Application, these Allowed Operations are configured automatically.

Network Architecture

The diagram below displays the connections used for SimpleAPI operations.

Connection 1: From API users to the Azure API Management (APIM) service (Frontend).

In this connection, API users connect to the APIM service using HTTPS. The use of APIM is optional; without it, API users will connect directly to the SimpleAPI component.

When using APIM:

A valid certificate must be used for the Azure API Service domain name.
Authorization by Subscription key (using HTTP header 'X-Subscription-Key') must be configured for APIM.
Azure API Service security mechanisms, for example, QoS policies must be used for endpoint protection.

Connection 2: From APIM to the SimpleAPI application (Backend).
In this connection, APIM directs authorized traffic to the Kubernetes Ingress controller. When using APIM, the Kubernetes Ingress controller should be connected to exclusively receive connections from APIM only, dropping all other incoming connections. We recommend using a private vNet connection between APIM and Kuberenetes rather than one over the public Internet.

Without APIM, the Ingress controller must receive incoming connections from all external sources.

Connection 3: From the SimpleAPI application to CloudBlue Commerce (Backend).

In this connection, the SimpleAPI core application communicates with the brands.

The SimpleAPI pod must be allowed to access CloudBlue Commerce branding URLs in case Kubernetes is restricting outgoing traffic.

Connection 4: From the SimpleAPI application to the Onboarding application (Backend).

In this connection, the SimpleAPI application instance connects to the Onboarding application to automate provisioning of new API users and their credentials.

Connection 5: From the Onboarding application to APIM.

In this connection, the Onboarding application connects to APIM to create a new subscription for the SimpleAPI product.

Dependencies

To work correctly, SimpleAPI requires the following components to be installed:

CloudBlue Commerce 20.5 with the latest hotfixes installed.
User and Account Management 1.2.1262 or later.
Identity Service 2.0.100.
Order Management 1.4.322 or later.
Reporting and Data Export (RDE) 2.2.266 or later.
Service applications (if used):
- Azure CSP 7.7.5 in combination with SimpleAPI 1.5.915

Additional Components

Onboarding Application

SimpleAPI includes a component that allows resellers to onboard themselves for access to the SimpleAPI service. This component exposes a service plan which can be made available for resellers to subscribe to and will automatically create Azure API Management subscription keys and a staff member with the correct privileges. It also adds a screen into the UX1 Reseller Control Panel that lets a reseller see their subscription key, user, and documentation links.

After subscribing to the service plan, the onboarding application will use the information from the reseller contact information to create a new user and cause CloudBlue Commerce to send an email to the reseller admin for setting up the user’s password.

Mock API

SimpleAPI includes the ability to run the API service in a simulated mode. In this mode, API requests made are not forwarded to CloudBlue Commerce and instead responses are simulated. The main purpose of this is to allow resellers to test their code safely, without adversely affecting their production account.

When resellers send a request to create a record, SimpleAPI will store this information in memory to be used for further requests. In this manner, a reseller can test their code to see whether they can create a customer, and whether they can retrieve this information in subsequent API requests.

When running the Mock API, please consider the following.

A separate list of valid user names is maintained within SimpleAPI itself.
Passwords are not verified for users, as the accounts do not exist.
Only several fake products are shown in the product catalog.
A reset of the API service will clear all additions and changes to the mock API data.
Resellers should not store personally identifiable information (PII) in Mock API.
Resellers will not have the ability verify their data in the CloudBlue Commerce user interface.