The REST Gateway 2.0 Gets a Re-Model (formerly, the REST Client)

Source: Photo by benjamin lehman on Unsplash

The REST Gateway provides you with a well known interface to your Aerospike Database, and a Swiss army knife-like solution to a variety of architectural problems where you might not want to integrate a full fledged Aerospike client into every application.

Re-Name and Refresh

The Aerospike REST Client is now the REST Gateway 2.0, including a major overhaul. We've added support for Aerospike Database server 6.0 and server 6.1 features, as well as complete retooling of the Operations API. These new features come with some deprecations and breaking changes, which this post will cover.
Here are the new features and changes:

• A new Operations API backed by swagger documentation. Deprecation of /v1/operation and /v1/execute endpoints.
• Query support with query by partition, response pagination, and secondary index filtering. Deprecation of /v1/scan endpoint.
• Batch Write, Batch Delete, and Batch UDF support. Rewrite of old /v1/batch API. This causes a breaking change.
• The ability to read and write to nested Complex Data Types (CDT). Rewrite of old CTX API. This causes a breaking change with /v1/operation and /v1/execute endpoints.
• Prometheus-compatible metrics for spring-boot, tomcat, and the resilience4j circuit breaker via the /actuator/prometheus endpoint.

Lastly, we renamed the REST Client to the REST Gateway for a few reasons. Most notably, the Gateway was never really a client but a piece of useful middleware that uses a client under the hood. So keep this in mind when searching the documentation.

Operations V2

Rest Gateway 2.0 marks the release of a new API which we think you will find easier to understand and more robust. The old operations API had its benefits but could be difficult to use in practice. The schema of each model was highly restricted, causing some bloat, and while It worked well for basic ops, it had problems with list and map operations and lacked support for Bit and HLL ops.
Every available Operation model has been redesigned and is now documented in our API documentation. 

Query by Partition

Aerospike server 6.0 added the ability to query by partition and paginate queries. Before the release of Gateway 2.0, we only supported scans, now called Primary Index Queries (PI query), which could only scan one partition at a time before returning the provided number of maxRecords. Throughput and potential use cases were limited. Now, with query partition, we can query partitions concurrently while still allowing for pagination via a returned token. We also support Secondary Index Queries (SI query) by providing an optional query filter.
 
Note: /v1/query endpoints currently only provide a way to perform foreground PI and SI queries. Use /v1/execute for background queries.

/v1/query provides a few new endpoints:

• /v1/query/<namespace> query an entire namespace
• /v1/query/<namespace>/<set> query a set
• /v1/query/<namespace>/<begin>/<count> query <count> sequential partitions of a namespace starting at <begin>
• /v1/query/<namespace>/<set>/<begin>/<count> query <count> sequential partitions of a set starting at <begin>

Pagination

To use pagination, provide the maxRecord query parameter (default 10,000) to specify the desired page size. To receive a token to be used for your next page request, provide the getToken=true query parameter (default: false). A token will then be received in the response body that can be used in the next request.

Filtering

Another major benefit of queries is providing an optional filter on a sindex. Furthermore, with Aerospike Server 6.1, sindexs can now be applied to nested CDTs. The following filters are currently supported, and the schemas can be found in our API documentation. 

• QueryEqualsStringFilter
• QueryEqualLongFilter
• QueryRangeFilter
• QueryContainsStringFilter
• QueryContainsLongFilter
• QueryGeoWithinPolygonFilter
• QueryGeoWithinRadiusFilter
• QueryGeoContainsPointFilter

New Batch API

Aerospike Server 6.0 added support for BatchWrite, BatchDelete, and BatchUDF commands to complement the existing BatchRead command. BatchWrite allows you to define a list of operations to perform on a record. These operations can contain both reads and writes. BatchDelete allows you to delete a record and filter based on generationPolicy or use a filter expression. BatchUDF allows you to run server-side User Defined Functions (UDFs) on a given record. BatchRead allows you to read specific bins from a record or CDTs using read operations.

Before Gateway 2.0, you had to use the /v1/batch endpoint to read different bins from different records, as opposed to the /v2/operate/read endpoint, which allows you to read the same bins from multiple records. The old /v1/batch endpoint also did not support reading from CDTs. To add support for BatchWrites, BatchDeletes, and BatchUDFs, we redesigned the body of the /v1/batch endpoint to support all four types rather than just a BatchRead. Another added benefit of the new API is that every Batch object type can specify its own unique policy.

You can take a look at the batch API documentation and schemas in our swagger documentation.

Note: Batch operations are not the same as multi-record transactions. Their execution is not guaranteed to be in the order provided.

Try it out!

Thank you for reading! If you need help or have problems, feel free to open an issue on GitHub or ask a question on the Aerospike Community Forum.