Backend: API Design

Last Updated: 2025-01-17
Phase: Phase 0 (Planning)
Status: Draft — finalize in Phase 1
Owner: Backend Architect
References:

/docs/backend/architecture.md
/docs/backend/payment-flow.md
/docs/backend/security.md

1. Principles

REST with versioning (/api/v1), consistent envelope and errors.
Tenant-scoped resources; role-based authorization.
Idempotent ingestion/webhook endpoints; trace IDs for debugging.

Resource set is archetype‑specific. Endpoints below are a pipeline/classification example — adapt for chat‑first, generation, or automation products.

2. Core Resources (high-level)

/auth — login, tenant context, token refresh.
/tenants — tenant profile, roles, invites.
/integrations — connect sources (OAuth2/webhooks), view health, rotate secrets, webhook endpoints.
/records — list/filter, detail (raw + normalized + reasoning), bulk actions, reprocess.
/rules — CRUD, enable/disable, test/preview, stats.
/processing — trigger re-evaluation (rules → embeddings → LLM), inspect outcomes.
/approvals — approval queue, approve/override, optional rule creation.
/reports — dashboards/summary generation, export status/download.
/billing — session/portal links, subscription status (webhook-driven).
/events — read-only event log feed for downstream agents.
/files/attachments — uploads/metadata (if exposed).

3. Payments/Billing (Provider-agnostic)

POST /billing/session — create checkout session for subscription/plan change.
GET /billing/status — current subscription status (webhook-driven source of truth).
GET /billing/portal — customer portal link for payment method/plan management.
POST /billing/webhooks/provider — verify signature; idempotent subscription updates; log billing events.

4. Ingestion/Webhooks

Receivers for external providers (e.g., /integrations/webhooks/{provider}): verify signature, dedupe, enqueue to BullMQ; emit INGESTED with source_agent.

5. Processing & Approvals

POST /processing/run — trigger re-evaluation for a scoped set (source/date/status).
POST /approvals/{id}/approve — accept decision; log APPROVED.
POST /approvals/{id}/override — override outcome; optional rule payload; log APPROVED and RULE_CREATED when applicable.

6. Events

GET /events — read-only feed (paginated) for downstream agents/clients; filters: tenant, type, time range, source_agent.

7. Response Envelope (example)

{
  "data": { ... },
  "error": null,
  "meta": { "traceId": "..." }
}

Errors: data = null, error with code/message/context.

2.7 KiB Raw Blame History Unescape Escape