# @dci/api — DataCenterIndex REST API

Fastify 5 service exposing the public read API (/api/v1/*) consumed by apps/web, and a token-protected admin API (/api/admin/*) for connector operations, document forensics, reconciliation and curation. Response types are the contract in packages/core/src/api-types.ts.

pnpm --filter @dci/api dev        # tsx watch, port API_PORT (8311)
pnpm --filter @dci/api start
pnpm --filter @dci/api typecheck
pnpm --filter @dci/api test       # vitest: query interpretation + integration against the local Postgres (.env)

Docs: GET /api/v1/docs (Swagger UI), GET /api/v1/openapi.json.

# Conventions

• Envelope on every /api/v1 response: { data, meta, sources }. meta carries total/page/perPage, generatedAt and, where a figure is derived, methodology. sources (detail endpoints) lists the SourceRefs behind the provenance / events shown.
• Errors: { error, statusCode, details? } — 400 with zod issues for bad query/body, 404 for unknown entities and routes, 401 for admin, 429 for rate limits.
• Caching: in-process LRU + Redis (dci:api:cache:*), key = route + normalized query, TTL per route family (dashboard 60 s, lists 120 s, details 300 s, map 300 s, events/news 30 s, search 60 s, sitemap 600 s). Headers: Cache-Control: public, max-age, s-maxage=<ttl>, stale-while-revalidate, weak ETag (independent of generatedAt; If-None-Match → 304), X-Cache: HIT|MISS. Disable with DCI_API_CACHE=0. Admin writes bust the affected prefixes (/datacenters, /dashboard, /map, /events).
• Ids or slugs are accepted everywhere a :slug appears; a facility whose merged_into is set redirects to its survivor in the detail endpoint and is hidden from lists.
• MW methodology: mw = COALESCE(it_capacity_mw, total_power_mw, planned_power_mw). knownMw sums operational/expansion/partially_operational facilities, constructionMw under_construction, plannedMw rumored/proposed/announced/permitting/approved/delayed (planned figure first). Per-facility estimates keep their mwIsEstimate flag; nothing is invented.
• Rate limit: 240 req/min per IP on public routes (X-RateLimit-* headers), 60/min on admin. Client IP is taken from X-Forwarded-For / X-Real-IP only when the peer is a trusted proxy (DCI_TRUSTED_PROXIES, default 127/8, 10/8, 172.16/12, ::1).
• Logging: pino JSON on stdout. Every request is also batched into ClickHouse api_requests (never fatal; DCI_API_CH_LOG=0 disables). /api/metrics exposes Prometheus text (requests by route/status, latency histogram, cache hits/misses, memory cache size, pool max).

# Public routes (/api/v1)

System: GET /api/health (no I/O), GET /api/ready (Postgres ping, Redis reported), GET /api/metrics.

# Admin routes (/api/admin, header x-dci-admin-token: $DCI_ADMIN_TOKEN)

Constant-time token compare; 401 otherwise, 503 when the token is not configured. All responses no-store.

# Environment

In development the repo-root .env is loaded automatically (process.loadEnvFile, never overriding set variables).

# Layout

src/main.ts              entry (env, graceful shutdown)
src/app.ts               Fastify app: plugins, error handling, hooks, route registration
src/env.ts               typed env
src/cache.ts / redis.ts  LRU + Redis response cache; ioredis clients
src/queues.ts            BullMQ producers (crawl / maintenance)
src/storage.ts           MinIO reader (zstd / gzip)
src/metrics.ts           Prometheus registry     src/telemetry.ts  ClickHouse api_requests batch
src/lib/                 http (envelope, ETag, errors), params (zod), route (publicGet), sql (fragments), rows (coercion), dto (mappers), resolve (slug/id, entity refs), source-history
src/repositories/        facilities, operators, countries, metros, cloud-regions, ixps, projects, events, map, search, rankings, dashboard, misc (stats/sources/news/sitemap), admin/{connectors,merge}
src/search/interpret.ts  query interpretation (pure, tested)
src/routes/              public/{facilities,graph,activity,discovery}, admin/{index,connectors,documents,matches,curation,devtool,ops}, system