REST API

The uniform interface is the central constraint that decouples clients from servers. It is defined by four sub-constraints:

• Resource Identification in Requests: Each resource (e.g., a vector collection) is identified by a unique URL, such as https://api.vectordb.com/v1/collections/customer_embeddings.
• Manipulation of Resources Through Representations: Clients interact with a resource's state via a complete representation (like JSON) sent in the request or response body.
• Self-Descriptive Messages: Each request/response contains all information needed for processing, using standard HTTP methods, status codes, and media types (e.g., Content-Type: application/json).
• Hypermedia as the Engine of Application State (HATEOAS): Responses can include hyperlinks to related actions, guiding the client through the API dynamically, though this is often simplified in machine-to-machine APIs.

Each client request to the server must contain all the information necessary to understand and process the request. The server does not store any session state about the client between requests. This constraint has major implications:

• Scalability: Any server can handle any request, enabling easy horizontal scaling.
• Reliability: No server-side session synchronization is required.
• Visibility: Each request can be understood in isolation. For a vector database API, this means authentication tokens, API keys, and all parameters for an operation (like query vectors, filters, and limits) must be included in every single HTTP request.

This constraint enforces a separation of concerns. The client (e.g., an application SDK) is responsible for the user interface and user state, while the server (the vector database) is responsible for data storage, business logic, and scalability. This separation allows:

• Independent Evolution: The client and server can be developed and deployed independently, as long as the API contract (the interface) is maintained.
• Portability: Client applications can be written in any language (Python, JavaScript, Go) and run on any platform.
• Scalability: The server component can be optimized for performance and reliability without impacting client implementations.

Responses from the server must be explicitly labeled as cacheable or non-cacheable. This constraint improves efficiency and performance by allowing clients and intermediaries to store and reuse responses for equivalent future requests.

• Cache-Control Headers: The server uses HTTP headers like Cache-Control: max-age=3600 to indicate how long a response can be cached.
• Performance Gains: Caching reduces latency for repeated requests and decreases load on the server.
• Idempotent Operations: Safe methods like GET (for reading a collection's schema) are ideal candidates for caching. For vector databases, query results are typically not cacheable due to their dynamic nature, but static metadata or schema information can be.

The architecture can be composed of hierarchical layers, where each layer has a specific function and cannot see beyond the immediate layer it is interacting with. This promotes:

• Load Balancers: Distribute requests across multiple server instances.
• API Gateways: Handle authentication, rate limiting, and request routing.
• Security Proxies: Enforce security policies.
• CDNs: Cache static assets. A client cannot tell whether it is connected directly to the end server or to an intermediary. For a vector database, this means a request might pass through a gateway managing API keys before reaching the actual database cluster, without the client's knowledge.

This is the only optional constraint. It allows servers to extend client functionality by transferring executable code, such as JavaScript scripts, which the client can execute. This enables the server to update client logic dynamically.

• Rare in Machine-to-Machine APIs: While common in web browsers (e.g., loading a JavaScript frontend), it is seldom used in backend-focused APIs like those for vector databases, where clients are typically SDKs or other services expecting predictable, structured data (JSON) rather than executable code.
• Flexibility vs. Complexity: It provides ultimate flexibility but reduces visibility and can introduce security concerns, making it unsuitable for most infrastructure-level APIs.

REST APIs map standard HTTP verbs to fundamental vector database operations on clearly defined resources.

• POST /collections: Creates a new collection (logical group of vectors).
• POST /collections/{id}/vectors: Inserts or upserts vectors into a collection.
• POST /collections/{id}/query: Executes a nearest neighbor search.
• GET /collections/{id}/vectors/{vector_id}: Retrieves a specific vector by ID.
• DELETE /collections/{id}/vectors/{vector_id}: Deletes a specific vector.
• DELETE /collections/{id}: Deletes an entire collection.

This resource-oriented design makes the API predictable and discoverable.

The request body for a similarity search defines the query vector, search parameters, and optional filters. A typical payload includes:

jsonCopy
{
  "vector": [0.12, -0.45, 0.87, ...],
  "top_k": 10,
  "include_metadata": true,
  "include_values": false,
  "filter": {
    "category": "documentation",
    "version": {"$gte": 2.0}
  }
}

Key fields:

• vector: The query embedding.
• top_k: Number of nearest neighbors to return.
• filter: A metadata expression for hybrid search, using operators like $eq, $in, $gte.
• include_metadata: Boolean to return stored metadata with results.

Search results are returned in a structured JSON array. For large result sets, pagination is controlled via limit and offset parameters or a next_cursor token.

Example Response:

jsonCopy
{
  "matches": [
    {
      "id": "vec_123",
      "score": 0.956,
      "metadata": {"title": "API Guide"},
      "values": [0.11, -0.44, 0.86, ...]
    }
  ],
  "next_cursor": "eyJpZCI6InZlY18yMDAifQ=="
}

• score: The similarity score (e.g., cosine similarity).
• next_cursor: An opaque token used to retrieve the next page of results, ensuring consistency during index updates.

Access is controlled via credentials passed in HTTP headers. Common patterns include:

• API Key: A secret token sent in the Authorization header (e.g., Authorization: Bearer db_apikey_xyz).
• mTLS (Mutual TLS): Both client and server authenticate with X.509 certificates for internal service-to-service communication.
• OAuth 2.0: For user-delegated access in third-party integrations, using short-lived bearer tokens.

Best practices mandate HTTPS/TLS 1.3 for all traffic to encrypt data in transit, including the vector payloads themselves.

Reliable operations depend on idempotent requests and clear error codes.

• Idempotency: Operations like PUT /vectors/{id} or a POST with a client-supplied idempotency_key ensure safe retries without duplicate side effects.
• HTTP Status Codes:
  • 200 OK: Success.
  • 400 Bad Request: Invalid payload (e.g., wrong vector dimension).
  • 429 Too Many Requests: Client exceeded rate limit.
  • 503 Service Unavailable: Database temporarily overloaded.

SDKs implement retry logic with exponential backoff for 429 and 5xx errors, often paired with a circuit breaker to prevent cascading failures.

While REST is ubiquitous, gRPC is often offered as a parallel high-performance option.

REST remains the default for broad compatibility, while gRPC is chosen for latency-sensitive internal systems.

A gRPC API is a high-performance, schema-driven interface that uses HTTP/2 and Protocol Buffers (protobuf) for binary serialization. It is the primary alternative to REST for internal, service-to-service communication with a vector database, offering:

• Lower latency and higher throughput due to binary payloads and persistent connections.
• Bi-directional streaming for real-time data ingestion or query results.
• Strongly-typed contracts via .proto files, enabling automatic client code generation. While REST is ideal for public-facing, web-compatible APIs, gRPC excels in microservices architectures where performance is critical.

An API endpoint is a specific URL where a client sends HTTP requests to perform an operation on a vector database resource. Each endpoint corresponds to a function, such as inserting vectors or executing a search.

Common vector database REST endpoints include:

• POST /v1/collections/{id}/vectors - Insert vectors.
• POST /v1/collections/{id}/query - Perform a nearest neighbor search.
• GET /v1/collections - List all collections. Endpoints are defined by the API's path, HTTP method (GET, POST, PUT, DELETE), and expected request/response schema.

The OpenAPI Specification is a standard, machine-readable format (YAML or JSON) for describing RESTful APIs. For a vector database, an OpenAPI document defines:

• All available endpoints, methods, and parameters.
• The exact structure of request bodies (e.g., vector arrays, metadata) and responses.
• Authentication methods and data models. This specification enables the automatic generation of interactive documentation, client SDKs in multiple languages, and server stubs, ensuring consistency and reducing integration time.

Hybrid search combines vector similarity search with structured metadata filtering in a single query. A REST API for a vector database typically implements this via a filter parameter in the query payload.

Example Query Payload:

jsonCopy
{
  "vector": [0.1, 0.2, ...],
  "top_k": 10,
  "filter": {"category": "document", "status": "published"}
}

This executes a nearest neighbor search but only returns results where the metadata matches the filter, enabling precise, context-aware retrieval.

Idempotency is a critical property of certain API operations where making the same request multiple times produces the same result as making it once. For vector database APIs, this is essential for reliable retries in distributed systems.

Idempotent methods include:

• PUT (e.g., updating a vector's metadata with a specific ID).
• DELETE (deleting a vector by ID).
• Idempotent POST operations, often using a client-supplied idempotency key in the request header. This ensures that network timeouts or client retries do not cause duplicate vector inserts or inconsistent state.

An API Gateway is an intermediary service that sits in front of a vector database's REST API, acting as a unified entry point. It handles cross-cutting concerns, allowing the core database service to focus on data operations.

Key functions of an API Gateway include:

• Request Routing & Composition: Directing calls to appropriate backend services.
• Authentication & Authorization: Validating API keys or JWT tokens.
• Rate Limiting & Throttling: Enforcing usage quotas per client or tenant.
• Metrics & Logging: Centralized observability for all API traffic.
• SSL/TLS Termination: Offloading encryption/decryption overhead.