With the recently announced Aerospike REST Client it is now simple to communicate with Aerospike using the same paradigms and tools that are already being utilized as part of a modern web application. This enables developers to communicate with Aerospike using previously unsupported languages, and to position the Database into an existing microservices architecture.
Although there’s an old blog post “Building a RESTful Web Service with Spring Boot and Aerospike” from 2013; utilizing the REST Client is now the suggested modern approach.
At launch the Aerospike REST client supports: A basic cluster information command, CRUD operations on Aerospike Records, application of multiple Operations to a single Record, retrieval of multiple records with a single request, execution of information commands, management of secondary indices, and user and role management.
These different functionalities are exposed through distinct endpoints:
/v1/cluster # Basic information about the Aerospike cluster/v1/kvs # CRUD operations on Aerospike records/v1/operate # Complex operations on Aerospike Records/v1/batch # Retrieval of multiple records in a single request/v1/info # Issue info commands to the Aerospike Cluster/v1/index # Secondary index management/v1/users # Manage users and permissions./v1/roles # Manage roles.
To retrieve a record from Aerospike it just takes a simple GET request to an endpoint.
To create a record, just pass a JSON payload along with a POST request.
The following examples, using the fantastic Python Requests library, demonstrate basic usage of the REST Client. For the full code from these snippets see The simple REST usage example in the REST Client usage repository.
The examples assume that the REST client is reachable at localhost:8080
Our first example uses Create/Read/Update/Delete operations so we will be utilizing the KVS endpoint.
Aerospike uniquely identifies records with a Namespace/Set/Userkey combination, so we define those as well. For more information on the Aerospike storage layout see Aerospike Data Model .
All of the examples in this section will modify the same record, so we can define a single endpoint.
Aerospike records contain bins, which can be thought of as maps from strings to objects. Our basic bins contain some information about a sample user: ‘Bob’
To store the record into Aerospike:
To return the record we just stored:
Now let’s change Bob’s favorite color to ‘Orange’. This uses a Patch to update an existing record:
Now let’s replace the entire record with a new collection of bins:
Now, to clean up, let’s delete the record:
Trying to fetch the record now will return a 404 error so the response will be an Error Object:
Performing Multiple Operations on the same record
For a more involved set of operations, we will use the operate endpoint. Suppose that we are storing the following information about a user:
First we create and store an initial record representing a user:
Now let’s give a last name to Bob, keep the ‘name_length’ bin in sync with his new name, and add a bin to indicate his company. To do that, we will append a string to the ‘name’ bin, increment the ‘name_length’ bin, and create a new bin named ‘company’
To do this we build an array of JSON objects representing operations:
For a complete list of supported operations see: REST Client operations .
To perform the changes we first build the URI for the operation on the record; we utilize a different endpoint than we previously did for simple record actions:
Now to apply the operation we POST our array of operations to the specified endpoint:
To fetch the record we can utilize the KVS endpoint defined earlier:
These were just a small sample of the operations enabled by the REST client. It enables new products and existing applications to utilize Aerospike in new and exciting ways, and we’re looking forward to seeing what will be built with it.
For the code in this blog, and more complex examples, check out the REST Client usage examples.