Skip to main content

57. REST API for Cassandra Module

Status: Accepted Date: 2025-07-06

Context​

We have decided to use Cassandra for storing time-series data within a dedicated mercury-cassandra module (adr://cassandra-timeseries). Now, we need to decide how other services within the Mercury ecosystem will interact with this module to read and write data. We could have services communicate with it directly via a language-specific driver, or expose its functionality over a network protocol.

Decision​

The mercury-cassandra module will expose its functionality through a standard, well-defined RESTful API. It will be a standalone microservice with NestJS controllers that handle HTTP requests.

For example, to retrieve OHLCV data, a client would make a GET request to an endpoint like /api/v1/ohlcv/BTC-USDT?from=...&to=...&granularity=1h. To write data, a client would POST to an endpoint like /api/v1/ohlcv.

This approach abstracts the underlying Cassandra database completely. Clients of this service do not need to know that Cassandra is being used; they only need to know how to speak HTTP and JSON.

Consequences​

Positive:

  • Technology Agnostic: Any service in any programming language can easily interact with the Cassandra module, as HTTP/REST is a universal standard. This promotes loose coupling.
  • Clear Contract: The REST API, defined with OpenAPI/Swagger, serves as a clear, well-documented contract for the service's capabilities.
  • Encapsulation: The complexities of interacting with Cassandra (e.g., managing connections, building CQL queries, handling paging state) are completely encapsulated within the mercury-cassandra service. Clients have a much simpler interface.
  • Leverages Existing Framework: We can use our existing NestJS framework knowledge and tooling to quickly build and document these controllers.

Negative:

  • Performance Overhead: There is a performance overhead associated with serializing/deserializing data to JSON and sending it over HTTP, compared to a direct binary database protocol.
  • Not Ideal for Streaming: REST is a request-response protocol and is not well-suited for streaming large amounts of data.

Mitigation:

  • Overhead is Acceptable: For the intended use case (querying historical data for analysis, bulk ingestion), the overhead of HTTP is acceptable and the benefits of a standard, decoupled interface outweigh the performance cost. This service is not intended for ultra-low-latency real-time tick data.
  • Bulk Endpoints and Pagination: For large data operations, we will design bulk endpoints and use standard pagination techniques to handle large datasets efficiently over REST. For true real-time streaming, a different solution (like WebSockets or a direct connection to a message broker) would be used, but that is outside the scope of this module's request-response API.
  • API Versioning: The API will follow our established versioning strategy (adr://api-versioning) to allow it to evolve without breaking client integrations.