Rest Server Rest Server protocol schemas
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
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); 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
Property Type Required Description method Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>✅ HTTP method path string✅ URL path pattern summary stringoptional Operation summary description stringoptional Operation description
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)
createreadupdatedeletelist
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
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
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 maskObjectFields boolean✅ [ADR-0106 D8] Mask served object schemas to the caller's readable fields endpoints { types: boolean; items: boolean; item: boolean; schema: boolean }optional Enable/disable specific endpoints
Property Type Required Description version string✅ API version (e.g., v1, v2, 2024-01) basePath string✅ Base URL path for API apiPath stringoptional 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 neveroptional [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. Run os migrate meta --from 16 to rewrite existing sources automatically. 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
Property Type Required Description api { version: string; basePath: string; apiPath?: string; enableCrud: boolean; … }optional REST API configuration crud { operations?: object; patterns?: Record<string, object>; dataPrefix: string; objectParamStyle: Enum<'path' | 'query'> }optional CRUD endpoints configuration metadata { prefix: string; enableCache: boolean; cacheTtl: integer; maskObjectFields: boolean; … }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, object> }optional Route generation configuration openApi31 neveroptional [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.
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
ObjectStack