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 package includes SimpleAPI Core Application and 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, 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
- CloudBlue Commerce 21.0.
- User and Account Management 1.2.1262 or later.
- Identity Service 2.0.100.
- Order Management 1.9.562 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
SimpleAPI Onboarding Application
The SimpleAPI Onboarding Application is included in the SimpleAPI package and allows you to provide your resellers with access to SimpleAPI and to charge per API request.
The SimpleAPI Onboarding Application 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.
SimpleAPI Mock Application
The SimpleAPI Mock Application is included in the SimpleAPI package and allows you to run the API service in simulation mode. In this mode, API requests 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.