SingleStoreDB is a distributed SQL database that scales out to power some of the largest enterprise data applications at companies like Akamai, Dell, Uber and IEX Cloud. Now with our Management API (REST) it is easier than ever to deploy SingleStoreDB for all your data applications.
While many users are aware that SingleStoreDB can scale compute horizontally to increase performance, it is less well known that many of these companies have now deployed SingleStoreDB across a wide range of applications and workloads.
SingleStoreDB excels at both transactional & analytics workloads making it an ideal fit across various parts of the business — from customer facing and SaaS applications, to internal operations, telemetry, IOT, Transportation and operational machine learning. But deploying data across some of the largest global enterprises in the world requires automation and integration with existing tools.
The new Management API for Singlestore Helios is a REST API that allows you to deploy, manage and operate SingleStoreDB at the largest scales. With Tier 1 customers in cybersecurity and financial services managing tens of thousands of active SingleStoreDB deployments, and SaaS applications driving on-demand creation and termination of databases, the SingleStoreDB Management API is a critical tool in meeting the needs of modern and real-time enterprise applications.
And as of today, it’s now available to all of our customers to enable the deployment and management of Singlestore Helios at the largest enterprise scale.
Why Did We Choose REST?
REpresentational State Transfer, or REST, is an architectural style for providing standards between computer systems on the web. These standards make it easier for systems to communicate with each other. REST-compliant systems, often called RESTful systems, are primarily characterized by being stateless and separating the concerns of client and server, although there are several other constraints.
We worked with many of our customers when designing the Management API, and chose REST for our API to ensure that it is easy to use and easy to integrate with existing enterprise infrastructure.
Stateless
RESTful applications must be stateless, meaning that there is no session information retained by the server. Any relevant session data is sent to the server by the client in such a way that every request can be understood in isolation, without having knowledge of previous messages.
This means management operations for SingleStoreDB are secure and reliable, which is critical when operating mission critical internal and customer facing applications.
Separation of Concerns
When designing RESTful applications, the implementation of the client and the implementation of the server can be done independently, without one knowing about the other.
This means that the code on the client side can be changed at any time without affecting the server operations, and the code on the server side can be changed without affecting client operations.
In addition, different client languages can use the same REST endpoints to perform the same actions and receive the same responses.
Making REST Requests
A client makes a request to the server in order to retrieve or modify data on the server. For our purposes we will be using HTTP. An HTTP request generally consists of:
- An HTTP verb, which defines what kind of operation to perform
- A header, which allows the client to pass along information about the request
- A path to a resource
- An optional message body containing data
HTTP verbs:
An HTTP verb describes what type of action is being requested. Some of the more common verbs are:
GET — retrieve a specific resource or collection of resources
POST — create a new resource
PATCH — update a specific resource
DELETE — remove a specific resource
Management API Endpoints
In the SingleStoreDB Management API, you can create, retrieve, update, suspend, resume and delete workspaces. The following are the endpoints for working with workspaces (note that these URLs will not work from a browser due to missing authentication information):
GET https://api.singlestore.com/v1/workspaceGroups
Retrieves all of the workspace groups for the current user.
POST https://api.singlestore.com/v1/workspaceGroups
Creates a new workspace group.
GET https://api.singlestore.com/v1/workspaces?workspaceGroupID={workspa
cegroupID} Retrieves workspaces of the workspace group.
POST https://api.singlestore.com/v1/workspaces
Creates a new workspace.
GET https://api.singlestore.com/v1/workspaceGroups/{workspaceGroupID} Retrieves the workspace group with the given id.
GET https://api.singlestore.com/v1/workspaces/{workspaceID} Retrieves the workspace with the given id.
DELETE https://api.singlestore.com/v1/workspaceGroups/{workspaceGroupID} Terminates the workspace group with the given id.
DELETE https://api.singlestore.com/v1/workspaces/{workspaceID} Terminates the workspace with the given id.
PATCH https://api.singlestore.com/v1/workspaceGroups/{workspaceGroupID} Updates the workspace group with the given id. The body of the request contains a JSON document with the following fields:
{
"name": "<name>",
"adminPassword": "<adminPassword>",
"firewallRanges": [
"<ip address>",
"<ip address>"
]
}The official documentation for the Management API can be found here.
Authentication
The Management API authenticates requests using a unique API key. You can generate this key on the Singlestore Helios portal — here’s how:
- From the Singlestore Helios portal, select the organization from the navigation pane.
- Select API keys > Create API key.
- Specify a name and expiration date for the API key.
- Select Create.
NOTE: The API key is displayed only once! Be sure to copy and securely store the API key.
Once an API key has been obtained, use the Authorization header with each HTTP request:
Authorization: Bearer <API key>
Calling the API With Python
As a simple example, the following Python code will make a request to the Management API to retrieve all of the workspace groups for the current user. Note that a valid API key must be provided.
import requests
url = "https://api.singlestore.com/v1/workspaceGroups"
payload={}
headers = {
'Authorization': 'Bearer 454c736a37ad628ab370e9c6d5d1b8664042360c2025b551b999b7c82c8c205f'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)All current active workspace groups will be displayed:
[
{
"name": "demo",
"workspaceGroupID": "a25832c6-0776-4c2b-8cc4-68ddc6f648af",
"createdAt": "2022-06-29T18:05:39.037486Z",
"regionID": "99b1a977-cde0-496f-8c2e-0946b2f444db"
},
…
]Calling the API With cURL
The same endpoint as above can be accessed via curl, a command line tool for transferring data via multiple network protocols, such as HTTP.
curl --request GET 'https://api.singlestore.com/v1/workspaceGroups \
--header 'Authorization: Bearer <API key>'Generating OpenAPI Clients
Included with the Management API is an OpenAPI specification definition. This definition can be used as input to a variety of tools (such as Swagger Codegen) to generate client SDKs in many languages.
Getting Started
Using SingleStoreDB with the Management API is simple, and you can get started completely free with our cloud trial. For more details on how to develop using the Management API, you can also check out our API Reference documentation.
We hope that you will provide us feedback (you can do that on our Forum) on how you are using the Management API to scale SingleStoreDB across your unique applications and workloads.
