Nest Engineering Docs
Interface

Local development

Run, debug, and test Interface locally

Prerequisites

  • uv and Python 3.13.
  • Environment variables for SPANNER_INSTANCE_ID and SPANNER_DATABASE_ID.
  • Google Application Credentials when targeting dev/prod Spanner (not required for the emulator).

Required environment

export SPANNER_INSTANCE_ID="..."
export SPANNER_DATABASE_ID="..."

Optional environment

# Recommended for local dev when metadata is unavailable
export GCP_PROJECT_ID="..."

Google Application Credentials

# Required for dev/prod Spanner access
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

If you're targeting the Spanner emulator, you do not need GOOGLE_APPLICATION_CREDENTIALS. Configure the emulator endpoint instead.

Install dependencies

# From repo root
uv sync --all-packages

Run locally

# From repo root
uv run --package interface granian --interface asgi services.interface.main:app --host 0.0.0.0 --port 8080 --workers 1 --loop uvloop

Sanity checks

curl http://localhost:8080/api/v1/health

Example request

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $INTERFACE_API_KEY" \
  -d '{"organization_id": "ORG_ID", "limit": 10, "offset": 0}' \
  http://localhost:8080/api/v1/organizations/search

Tests

# From repo root
uv run --package interface pytest -q

Debugging tips

  • 401 Unauthorized usually indicates a missing or invalid X-API-Key.
  • Startup failures often come from missing secrets or Spanner connectivity.

Last updated on

Data model

Storage, schemas, and data ownership for Interface

Operations

Deployments, SLOs, and monitoring for Interface