Skip to main content

API Conventions

Last reviewed: 2026-06-13
Maintained by: Engineering

The ZGRID API is the shared operating layer behind every product surface. These conventions keep managers, residents, technicians, and platform administrators on one consistent server contract.

Current conventions​

  • input validation is handled close to the route layer
  • business rules live in feature services
  • role, tenant, and organization scope checks must be enforced by the API
  • shared client contracts should stay aligned with packages/api-client

Auth Transports​

ZGRID supports more than one client shape, but not more than one security model.

  • browser-oriented web flows support cookie-based auth for login and refresh
  • mobile and API-style clients use bearer-token auth
  • both transport modes rely on the same API-enforced auth, scope, and business rules
  • docs should describe transport expectations at a high level rather than as replay/bypass instructions

Request-Origin Hardening​

Browser-style authenticated flows get additional origin protection because ZGRID serves both internal web workspaces and mobile/API clients.

  • unsafe cookie-auth requests are protected by request-origin checks against configured web origins
  • this protection is aimed at browser-style authenticated flows, not bearer-token API clients
  • docs should describe this as origin/referer hardening without detailing abuse-oriented edge cases

Rate Limiting​

Rate limiting is part of the platform protection layer, not a product feature.

  • write-sensitive and abuse-prone route groups use route-level rate limiting
  • the default store is in-process memory for local/dev/test work
  • hosted multi-instance environments can use a shared Redis-backed store
  • docs should explain rate limiting as a protective control and avoid publishing exact abuse-tuning thresholds

Upload Validation​

Attachment flows in ZGRID are designed around trust reduction, not filename trust.

  • upload flows validate actual file signatures, not only MIME types or filename extensions
  • supported attachment paths can use signed object-storage upload/download flows where storage is configured
  • docs should focus on allowed file classes and validation intent, not low-level exploit-relevant mechanics

Webhook Conventions​

External billing and delivery providers plug into the same principle: isolate the integration and verify inputs before processing them.

  • webhook endpoints are isolated from standard JSON parsing where raw-body signature verification is required
  • provider-specific webhook processing stays in dedicated integration services
  • docs should explain provider purpose, verification at a high level, and operational dependencies without exposing secrets

Key source areas​

  • routes: apps/api/src/routes
  • feature services: apps/api/src/features
  • typed client contracts: packages/api-client/src/index.ts
  • environment validation: apps/api/src/config/env.ts