Skip to content

rest-server.mdx

Latest commit

 

History

History
203 lines (133 loc) · 9.24 KB

rest-server.mdx

File metadata and controls

203 lines (133 loc) · 9.24 KB
Raw
title Rest Server
description Rest Server protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

REST API Server Protocol

Defines the REST API server configuration for automatically generating

RESTful CRUD endpoints, metadata endpoints, and batch operations.

Features:

  • Automatic CRUD endpoint generation from Object definitions

  • Standard REST conventions (GET, POST, PUT, PATCH, DELETE)

  • Metadata API endpoints

  • Batch operation endpoints

  • OpenAPI/Swagger documentation generation

Architecture alignment:

  • Salesforce: REST API with Object CRUD

  • Microsoft Dynamics: Web API with entity operations

  • Strapi: Auto-generated REST endpoints

**Source:** `packages/spec/src/api/rest-server.zod.ts`

TypeScript Usage

import { BatchEndpointsConfigSchema, CrudEndpointPatternSchema, CrudEndpointsConfigSchema, CrudOperation, EndpointRegistrySchema, GeneratedEndpointSchema, MetadataEndpointsConfigSchema, RestApiConfigSchema, RestServerConfigSchema, RouteGenerationConfigSchema } from '@objectstack/spec/api';
import type { BatchEndpointsConfig, CrudEndpointPattern, CrudEndpointsConfig, CrudOperation, EndpointRegistry, GeneratedEndpoint, MetadataEndpointsConfig, RestApiConfig, RestServerConfig, RouteGenerationConfig } from '@objectstack/spec/api';

// Validate data
const result = BatchEndpointsConfigSchema.parse(data);

BatchEndpointsConfig

Properties

Property Type Required Description
maxBatchSize integer ✅ Maximum records per batch operation
enableBatchEndpoint boolean ✅ Enable POST /data/:object/batch endpoint
operations { createMany: boolean; updateMany: boolean; deleteMany: boolean; upsertMany: boolean } optional Enable/disable specific batch operations
defaultAtomic boolean ✅ Default atomic/transaction mode for batch operations

CrudEndpointPattern

Properties

Property Type Required Description
method Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'> ✅ HTTP method
path string ✅ URL path pattern
summary string optional Operation summary
description string optional Operation description

CrudEndpointsConfig

Properties

Property Type Required Description
operations { create: boolean; read: boolean; update: boolean; delete: boolean; … } optional Enable/disable operations
patterns Record<string, { method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; path: string; summary?: string; description?: string }> optional Custom URL patterns for operations
dataPrefix string ✅ URL prefix for data endpoints
objectParamStyle Enum<'path' | 'query'> ✅ How object name is passed (path param or query param)

CrudOperation

Allowed Values

  • create
  • read
  • update
  • delete
  • list

EndpointRegistry

Properties

Property Type Required Description
endpoints { id: string; method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; path: string; object: string; … }[] ✅ All generated endpoints
total integer ✅ Total number of endpoints
byObject Record<string, { id: string; method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; path: string; object: string; … }[]> optional Endpoints grouped by object
byOperation Record<string, { id: string; method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; path: string; object: string; … }[]> optional Endpoints grouped by operation

GeneratedEndpoint

Properties

Property Type Required Description
id string ✅ Unique endpoint identifier
method Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'> ✅ HTTP method
path string ✅ Full URL path
object string ✅ Object name (snake_case)
operation Enum<'create' | 'read' | 'update' | 'delete' | 'list'> | string ✅ Operation type
handler string ✅ Handler function identifier
metadata { summary?: string; description?: string; tags?: string[]; deprecated?: boolean } optional

MetadataEndpointsConfig

Properties

Property Type Required Description
prefix string ✅ URL prefix for metadata endpoints
enableCache boolean ✅ Enable HTTP cache headers (ETag, Last-Modified)
cacheTtl integer ✅ Cache TTL in seconds
endpoints { types: boolean; items: boolean; item: boolean; schema: boolean } optional Enable/disable specific endpoints

RestApiConfig

Properties

Property Type Required Description
version string ✅ API version (e.g., v1, v2, 2024-01)
basePath string ✅ Base URL path for API
apiPath string optional Full API path (defaults to {basePath}/{version})
enableCrud boolean ✅ Enable automatic CRUD endpoint generation
enableMetadata boolean ✅ Enable metadata API endpoints
enableUi boolean ✅ Enable UI API endpoints (Views, Menus, Layouts)
enableBatch boolean ✅ Enable batch operation endpoints
enableDiscovery boolean ✅ Enable API discovery endpoint
enableOpenApi boolean ✅ Enable OpenAPI 3.1 spec & docs viewer endpoints
enableProjectScoping boolean ✅ Enable project-scoped routing for data/meta/AI APIs
projectResolution Enum<'required' | 'optional' | 'auto'> ✅ Project ID resolution strategy
requireAuth any optional [REMOVED] api.requireAuth was removed in @objectstack/spec 17 (#3963). Anonymous access to object data is now always denied — auth is a kernel concern, not a deployment posture. Delete the key. To publish something publicly, declare it: a public form view (sharing.allowAnonymous), a share link, or book.audience: 'public' — each derives its own narrow authorization instead of opening the whole data plane.
documentation { enabled: boolean; title: string; description?: string; version?: string; … } optional OpenAPI/Swagger documentation config
responseFormat { envelope: boolean; includeMetadata: boolean; includePagination: boolean } optional Response format options

RestServerConfig

Properties

Property Type Required Description
api { version: string; basePath: string; apiPath?: string; enableCrud: boolean; … } optional REST API configuration
crud { operations?: object; patterns?: Record<string, { method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; path: string; summary?: string; description?: string }>; dataPrefix: string; objectParamStyle: Enum<'path' | 'query'> } optional CRUD endpoints configuration
metadata { prefix: string; enableCache: boolean; cacheTtl: integer; endpoints?: object } optional Metadata endpoints configuration
batch { maxBatchSize: integer; enableBatchEndpoint: boolean; operations?: object; defaultAtomic: boolean } optional Batch endpoints configuration
routes { includeObjects?: string[]; excludeObjects?: string[]; nameTransform: Enum<'none' | 'plural' | 'kebab-case' | 'camelCase'>; overrides?: Record<string, { enabled?: boolean; basePath?: string; operations?: Record<string, boolean> }> } optional Route generation configuration
openApi31 any optional [REMOVED] RestServerConfig.openApi31 was removed in @objectstack/spec 17 (#4579, ADR-0049) — no runtime ever read it: the REST server forwards only api/crud/metadata/batch/routes, and the served /openapi.json is the pre-generated contract enriched with the live server URL and the registered objects, so webhook/callback definitions declared here never appeared in it. Delete the key. Config-driven OpenAPI 3.1 webhooks/callbacks documentation is a new capability and must arrive via the enforce route of ADR-0049 (a new ADR), not by re-declaring the key; for a real outbound webhook use Webhook from @objectstack/spec/automation.

RouteGenerationConfig

Properties

Property Type Required Description
includeObjects string[] optional Specific objects to generate routes for (empty = all)
excludeObjects string[] optional Objects to exclude from route generation
nameTransform Enum<'none' | 'plural' | 'kebab-case' | 'camelCase'> ✅ Transform object names in URLs
overrides Record<string, { enabled?: boolean; basePath?: string; operations?: Record<string, boolean> }> optional Per-object route customization