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 integeroptional (default: 200) Maximum records per batch operation enableBatchEndpoint booleanoptional (default: true) Enable POST /data/:object/batch endpoint operations { createMany: boolean; updateMany: boolean; deleteMany: boolean; upsertMany: boolean }optional Enable/disable specific batch operations defaultAtomic booleanoptional (default: true) Default atomic/transaction mode for batch operations
Property Type Required Description createMany booleanoptional (default: true) Enable POST /data/:object/createMany updateMany booleanoptional (default: true) Enable POST /data/:object/updateMany deleteMany booleanoptional (default: true) Enable POST /data/:object/deleteMany upsertMany booleanoptional (default: true) Enable POST /data/:object/upsertMany
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 stringoptional (default: "/data") URL prefix for data endpoints objectParamStyle Enum<'path' | 'query'>optional (default: "path") How object name is passed (path param or query param)
Property Type Required Description create booleanoptional (default: true) Enable create operation read booleanoptional (default: true) Enable read operation update booleanoptional (default: true) Enable update operation delete booleanoptional (default: true) Enable delete operation list booleanoptional (default: true) Enable list operation
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
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 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 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 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 stringoptional (default: "/meta") URL prefix for metadata endpoints enableCache booleanoptional (default: true) Enable HTTP cache headers (ETag, Last-Modified) cacheTtl integeroptional (default: 3600) Cache TTL in seconds maskObjectFields booleanoptional (default: true) [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 types booleanoptional (default: true) GET /meta - List all metadata types items booleanoptional (default: true) GET /meta/:type - List items of type item booleanoptional (default: true) GET /meta/:type/:name - Get specific item schema booleanoptional (default: true) GET /meta/:type/:name/schema - Get JSON schema
Property Type Required Description version stringoptional (default: "v1") API version (e.g., v1, v2, 2024-01) basePath stringoptional (default: "/api") Base URL path for API apiPath stringoptional Full API path (defaults to {basePath}/{version}) enableCrud booleanoptional (default: true) Enable automatic CRUD endpoint generation enableMetadata booleanoptional (default: true) Enable metadata API endpoints enableUi booleanoptional (default: true) Enable UI API endpoints (Views, Menus, Layouts) enableBatch booleanoptional (default: true) Enable batch operation endpoints enableDiscovery booleanoptional (default: true) Enable API discovery endpoint enableOpenApi booleanoptional (default: true) Enable OpenAPI 3.1 spec & docs viewer endpoints enableSearch booleanoptional (default: true) Enable structured search endpoints (deployment-wide search opt-out) enableProjectScoping booleanoptional (default: false) Enable project-scoped routing for data/meta/AI APIs projectResolution Enum<'required' | 'optional' | 'auto'>optional (default: "auto") Project ID resolution strategy requireAuth neveroptional [REMOVED] api.requireAuth was removed in @objectstack/spec 17. 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 list the mechanical edits for existing sources; apply them by hand. 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 enabled booleanoptional (default: true) Enable API documentation title stringoptional (default: "ObjectStack API") API documentation title description stringoptional API description version stringoptional Documentation version termsOfService stringoptional Terms of service URL contact { name?: string; url?: string; email?: string }optional license { name: string; url?: string }optional
Property Type Required Description envelope booleanoptional (default: true) Wrap responses in standard envelope includeMetadata booleanoptional (default: true) Include response metadata (timestamp, requestId) includePagination booleanoptional (default: true) Include pagination info in list responses
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 (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 version stringoptional (default: "v1") API version (e.g., v1, v2, 2024-01) basePath stringoptional (default: "/api") Base URL path for API apiPath stringoptional Full API path (defaults to {basePath}/{version}) enableCrud booleanoptional (default: true) Enable automatic CRUD endpoint generation enableMetadata booleanoptional (default: true) Enable metadata API endpoints enableUi booleanoptional (default: true) Enable UI API endpoints (Views, Menus, Layouts) enableBatch booleanoptional (default: true) Enable batch operation endpoints enableDiscovery booleanoptional (default: true) Enable API discovery endpoint enableOpenApi booleanoptional (default: true) Enable OpenAPI 3.1 spec & docs viewer endpoints enableSearch booleanoptional (default: true) Enable structured search endpoints (deployment-wide search opt-out) enableProjectScoping booleanoptional (default: false) Enable project-scoped routing for data/meta/AI APIs projectResolution Enum<'required' | 'optional' | 'auto'>optional (default: "auto") Project ID resolution strategy requireAuth neveroptional [REMOVED] api.requireAuth was removed in @objectstack/spec 17. 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 list the mechanical edits for existing sources; apply them by hand. 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 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 stringoptional (default: "/data") URL prefix for data endpoints objectParamStyle Enum<'path' | 'query'>optional (default: "path") How object name is passed (path param or query param)
Property Type Required Description prefix stringoptional (default: "/meta") URL prefix for metadata endpoints enableCache booleanoptional (default: true) Enable HTTP cache headers (ETag, Last-Modified) cacheTtl integeroptional (default: 3600) Cache TTL in seconds maskObjectFields booleanoptional (default: true) [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 maxBatchSize integeroptional (default: 200) Maximum records per batch operation enableBatchEndpoint booleanoptional (default: true) Enable POST /data/:object/batch endpoint operations { createMany: boolean; updateMany: boolean; deleteMany: boolean; upsertMany: boolean }optional Enable/disable specific batch operations defaultAtomic booleanoptional (default: true) Default atomic/transaction mode for batch operations
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'>optional (default: "none") Transform object names in URLs overrides Record<string, { enabled?: boolean; basePath?: string; operations?: Record<string, boolean> }>optional Per-object route customization
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'>optional (default: "none") Transform object names in URLs overrides Record<string, { enabled?: boolean; basePath?: string; operations?: Record<string, boolean> }>optional Per-object route customization
Property Type Required Description enabled booleanoptional Enable/disable routes for this object basePath stringoptional Custom base path operations Record<string, boolean>optional Enable/disable specific operations
ObjectStack