API Documentation

The SoftSlate Cloud Platform API provides comprehensive access to the platform with nearly 1,000 endpoints. This powerful API covers searching for, editing, adding, and deleting records for most entities in the system, giving you the same capabilities as the administrator console. You can use the API to customize and extend the functions of SCP to meet your specific business needs, synchronize data with your existing systems, or create entirely new user interface applications.

The API Explorer

The best way to get started with the SCP API is to visit the API Explorer. The link for the API Explorer appears under the Operations section of the administrator menu:

In one interface, the API Explorer (which uses the Swagger tool) lets you view all of the available API endpoints, including documentation about how they can be used, and the complete specifications for requests and responses:

Detailed documentation about each parameter and response field is accessible in this interface. To view the field-specific descriptions, click the "Schema" link and then click into the object that is used for the request or response. Here is an example of where to click for details about the response to the "Read Agreement" endpoint:

You can also actually run API requests directly in the Explorer if you set up an API User with appropriate permissions (see below). Open up one of the endpoints and click the "Try It Now" button to reveal a form that allows you to hit the endpoint. Be careful - doing so may affect your live data.

Public API Endpoints

Some API endpoints are publicly accessible without requiring authentication. These endpoints correspond to the public-facing features of your website and include essential e-commerce functions that your customers use, such as adding items to their shopping cart, and completing the checkout process.

API Authentication

The majority of the API consists of a comprehensive set of endpoints that allow you to manage and manipulate your site on the SCP platform. CRUD (create, read, update, and delete) functions are included for most entities in the system, along with numerous other useful endpoints for advanced functionality. To access these administrative endpoints, you must first set up an API User and authenticate with it.

How To Create And Manage API Users

To create an API User, log into the administrator interface with a user account that has superuser privileges, and navigate to the API Users link under the Operations section in the side menu. Click the plus icon to create a new API User.

You can provide a custom username for the API user, but the password is automatically generated for security purposes. The password is displayed on-screen immediately after you create the API user. Important: For security reasons, the password is never shown again after this initial display, so make sure to copy and store it in a secure location as soon as you create the user.

In addition to creating the API user, you must assign appropriate roles to it, or it will not have permission to perform any operations. As a security best practice, we strongly recommend limiting the assigned roles to only the specific functions that the API user absolutely needs to perform.

You can modify the username and assigned roles for each API User at any time through the administrator interface. However, you cannot change or retrieve the password once it's been set. If you lose or forget the password, you'll need to create a new API User and assign it the same roles as the previous one.

Basic Authentication

Each request to the administrative API endpoints uses Basic Authentication. To authenticate, you'll need to create a token using the API User's username and password with Base64 encoding, then include this token in a request header named "Authorization". The header value should have "Basic " prepended to the encoded token.

Here's an example implementation in Java:

xxxxxxxxxx
import org.apache.commons.codec.binary.Base64;
...
String base64ClientIdSec = Base64.encodeBase64String((user + ":" + password).getBytes());
headers.add("Authorization", "Basic " + base64ClientIdSec);

Here's an example implementation in Python:

xxxxxxxxxx
import base64
credentials = f"{username}:{password}" 
encoded_credentials = base64.b64encode(credentials.encode('utf-8')).decode('utf-8')
auth_header = f"Basic {encoded_credentials}"
headers = {"Authorization": auth_header}

Note: You can also perform the Base64 encoding separately using any Base64 encoding tool, and then use the pre-encoded value directly in your scripts.

The API Explorer (Swagger Interface) and Basic Authentication

You can use the built-in API Explorer (Swagger Interface) to test API calls by entering your API user credentials directly into the interface. Click the "Authorize" button at the top of the interface screen to enter the username and password before making your first request.

Please note that the username and password are not stored in the browser session when using the API Explorer, so you may be prompted to enter them again for subsequent requests. If your browser opens a dialog window asking for login details again, you can enter the credentials and instruct the browser to remember them for future requests during that session.

Next Steps: API Examples/Tutorials

We have published a few examples that demonstrate how you can use the API. In some of these examples, we are using AWS Lambda functions to communicate with the API, but you can use any system that supports sending HTTPS requests and parsing the reponses, which are in JSON format. Whatever your business need is, these examples should give you ideas about how to implement it. Please visit:

• How To Call an AWS Lambda Function To Perform Customizations

• How To Schedule a Job To Use an AWS Lambda Function To Update Content

• How To Use a Bash Script with Curl To Send Content Page Changes to SCP

Other Tools for Customizing and Extending SCP

The API is just one tool available for customizing SCP for your business.

• Customize the out-of-the-box customer interface with your own templates and UI elements: Design (JSP) Customizations

• Create custom fields to store special information, including collecting custom fields from customers during the ecommerce checkout process: Custom Fields

• Engage with us to develop your project! Find out more about SoftSlate's Services