The RestApp class provides a REST API implementation of the App interface, designed for production deployments. It exposes HTTP endpoints for data ingestion and querying, making it suitable for web services and API-based integrations.

​
Constructor

Create a new REST application with comprehensive API configuration. 
RestApp(
    sources,
    indices,
    queries,
    vector_database,
    context,
    endpoint_configuration,
    queue=None,
    blob_handler=None
)

​
Parameters

​
sources
Sequence[RestSource | DataLoaderSource]
required
List of sources that can be either REST sources for real-time data or data loader sources for batch processing. These define how data enters your system.
​
indices
Sequence[Index]
required
List of indices to be used by the REST application. These organize your vector spaces for efficient querying through the API.
​
queries
Sequence[RestQuery]
required
List of query configurations that define the available REST API endpoints for searching and retrieving data.
​
vector_database
VectorDatabase
required
Vector database instance for persistent storage. This is where your vectors will be stored and retrieved from.
​
context
ExecutionContext
required
Execution context that provides configuration and runtime settings for the REST application.
​
endpoint_configuration
RestEndpointConfiguration
required
Configuration for REST endpoints including routes, authentication, and API behavior settings.
​
queue
Queue[dict] | None
default:"None"
Optional messaging queue for persisting ingested data. Enables asynchronous processing and data durability.
​
blob_handler
BlobHandler | None
default:"None"
Optional blob handler for managing file uploads and binary data through the REST API.

​
Example

from superlinked import (
    RestApp, RestSource, Index, RestQuery,
    QdrantVectorDatabase, RestEndpointConfiguration
)

@schema
class ProductSchema:
    id: str
    name: str
    description: str
    price: float

product_schema = ProductSchema()

# Configure REST components
rest_source = RestSource(product_schema)
text_space = TextSimilaritySpace(text=product_schema.description)
index = Index([text_space])

# Define API queries
product_query = RestQuery(
    name="search_products",
    index=index,
    query_descriptor=query_descriptor
)

# Set up vector database
vector_db = QdrantVectorDatabase(
    url="http://localhost:6333",
    collection_name="products"
)

# Configure API endpoints
endpoint_config = RestEndpointConfiguration(
    base_url="/api/v1",
    enable_auth=True,
    rate_limit=100
)

# Create REST application
app = RestApp(
    sources=[rest_source],
    indices=[index],
    queries=[product_query],
    vector_database=vector_db,
    context=execution_context,
    endpoint_configuration=endpoint_config
)

​
Properties

​
data_loader_sources

data_loader_sources: Sequence[DataLoaderSource]
Returns the list of DataLoaderSource instances associated with the RestApp. These sources handle batch data loading operations. Returns: Sequence[DataLoaderSource] - A sequence of DataLoaderSource instances.

​
handler

handler: RestHandler
Returns the RestHandler instance that manages HTTP request processing and routing for the application. Returns: RestHandler - The REST request handler instance.

​
Inheritance

The RestApp extends the application hierarchy to provide REST-specific functionality: Inheritance Chain:
  • RestApp
  • → OnlineApp
  • → App
  • → ABC + Generic
  • → QueryMixin
This provides:
  • Base App functionality from App
  • Online processing capabilities from OnlineApp
  • Query operations from QueryMixin
  • HTTP API handling specific to RestApp

​
API Endpoints

​
Data Ingestion Endpoints

The RestApp automatically creates endpoints for data ingestion: 
POST /api/v1/ingest/{source_name}
Content-Type: application/json

{
  "data": [
    {
      "id": "1",
      "name": "Product Name",
      "description": "Product description",
      "price": 99.99
    }
  ]
}

​
Query Endpoints

Query endpoints are created based on your RestQuery configurations: 
POST /api/v1/query/{query_name}
Content-Type: application/json

{
  "query": "find similar products",
  "limit": 10,
  "filters": {
    "price": {"min": 50, "max": 200}
  }
}

​
Health Check Endpoints

Built-in endpoints for monitoring: 
GET /api/v1/health
GET /api/v1/ready

​
Production Features

​
Scalability

  • Horizontal Scaling: Deploy multiple instances behind a load balancer
  • Database Persistence: Persistent vector storage for production data
  • Async Processing: Queue-based data ingestion for high throughput

​
Security

  • Authentication: Configurable auth mechanisms
  • Rate Limiting: Built-in rate limiting for API protection
  • Input Validation: Automatic request validation against schemas

​
Monitoring

  • Logging: Comprehensive request and error logging
  • Metrics: Built-in performance metrics collection
  • Health Checks: Kubernetes-ready health endpoints

​
Use Cases

​
API-First Applications

Build vector search APIs for web and mobile applications: 
# E-commerce search API
ecommerce_app = RestApp(
    sources=[product_source],
    indices=[product_index],
    queries=[search_query, recommendation_query],
    vector_database=production_db,
    endpoint_configuration=api_config
)

# Deploy with uvicorn or gunicorn
# uvicorn app:ecommerce_app --host 0.0.0.0 --port 8000

​
Microservices Architecture

Deploy as a microservice in containerized environments: 
FROM python:3.9
COPY . /app
WORKDIR /app
RUN pip install superlinked
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

​
Real-Time Search Services

Provide real-time vector search capabilities: 
# Real-time recommendation service
recommendation_app = RestApp(
    sources=[user_interaction_source],
    indices=[user_preference_index],
    queries=[recommendation_query],
    vector_database=redis_db,
    queue=kafka_queue  # For real-time updates
)

​
Best Practices

​
Configuration Management

Environment Variables: Use environment variables for database URLs, API keys, and other configuration that varies between environments.

​
Data Handling

Batch Processing: Use DataLoaderSource for bulk data ingestion and RestSource for real-time updates.
Rate Limiting: Always configure appropriate rate limits to prevent API abuse and ensure fair resource usage.

​
Monitoring and Observability

Logging: Enable comprehensive logging for debugging and monitoring API usage patterns.
Error Handling: Implement proper error handling and return meaningful HTTP status codes and error messages.

​
Deployment Example

# Complete production setup
from superlinked import RestApp, RestExecutor

# Create executor with production configuration
executor = RestExecutor(
    sources=[rest_source, batch_loader],
    indices=[search_index],
    queries=[search_query, filter_query],
    vector_database=qdrant_db,
    endpoint_configuration=RestEndpointConfiguration(
        base_url="/api/v1",
        cors_enabled=True,
        rate_limit=1000,
        enable_auth=True
    )
)

# Run the application
app = executor.run()

# Deploy with production WSGI server
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000, workers=4)

​
Integration with Frontend

// Frontend integration example
const searchProducts = async (query) => {
  const response = await fetch("/api/v1/query/search_products", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer " + token,
    },
    body: JSON.stringify({
      query: query,
      limit: 20,
    }),
  });

  return await response.json();
};