Rest Server

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	`Object`	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	`Object`	optional	Enable/disable operations
patterns	`Record<string, Object>`	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	`Object[]`	✅	All generated endpoints
total	`integer`	✅	Total number of endpoints
byObject	`Record<string, Object[]>`	optional	Endpoints grouped by object
byOperation	`Record<string, Object[]>`	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	`Object`	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	`Object`	optional	Enable/disable specific endpoints

OpenApi31Extensions

Properties

Property	Type	Required	Description
webhooks	`Record<string, Object>`	optional	OpenAPI 3.1 webhooks (top-level webhook definitions)
callbacks	`Record<string, Object[]>`	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
documentation	`Object`	optional	OpenAPI/Swagger documentation config
responseFormat	`Object`	optional	Response format options

RestServerConfig

Properties

Property	Type	Required	Description
api	`Object`	optional	REST API configuration
crud	`Object`	optional	CRUD endpoints configuration
metadata	`Object`	optional	Metadata endpoints configuration
batch	`Object`	optional	Batch endpoints configuration
routes	`Object`	optional	Route generation configuration
openApi31	`Object`	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, Object>`	optional	Per-object route customization

On this page