rest-server.mdx

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 { BatchEndpointsConfig, Callback, CrudEndpointPattern, CrudEndpointsConfig, CrudOperation, EndpointRegistry, GeneratedEndpoint, MetadataEndpointsConfig, OpenApi31Extensions, RestApiConfig, RestServerConfig, RouteGenerationConfig } from '@objectstack/spec/api';
import type { BatchEndpointsConfig, Callback, CrudEndpointPattern, CrudEndpointsConfig, CrudOperation, EndpointRegistry, GeneratedEndpoint, MetadataEndpointsConfig, OpenApi31Extensions, RestApiConfig, RestServerConfig, RouteGenerationConfig } from '@objectstack/spec/api';

// Validate data
const result = BatchEndpointsConfig.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

---

Callback

Properties

Property	Type	Required	Description
name	string	✅	Callback identifier (snake_case)
expression	string	✅	Runtime expression (e.g., {$request.body#/callbackUrl})
method	Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>	✅	HTTP method for callback request
url	string	✅	Callback URL template with runtime expressions

---

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

---

OpenApi31Extensions

Properties

Property	Type	Required	Description
webhooks	Record<string, { name: string; description: string; method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; payloadSchema: string; … }>	optional	OpenAPI 3.1 webhooks (top-level webhook definitions)
callbacks	Record<string, { name: string; expression: string; method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; url: string }[]>	optional	OpenAPI 3.1 callbacks (async response definitions)
jsonSchemaDialect	string	✅	JSON Schema dialect for schema definitions
pathItemReferences	boolean	✅	Allow $ref in path items (OpenAPI 3.1 feature)

---

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	{ webhooks?: Record<string, { name: string; description: string; method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; payloadSchema: string; … }>; callbacks?: Record<string, { name: string; expression: string; method: Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'>; url: string }[]>; jsonSchemaDialect: string; pathItemReferences: boolean }	optional	OpenAPI 3.1 extensions configuration

---

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

---