Skip to content

rest-server.mdx

Latest commit

 

History

History
231 lines (151 loc) · 7.71 KB

rest-server.mdx

File metadata and controls

231 lines (151 loc) · 7.71 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 { 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
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 boolean ✅ Reject anonymous requests on ALL HTTP surfaces that reach object data (REST /data, /meta, GraphQL, raw-hono /data) with HTTP 401 (secure-by-default; set false to serve them publicly)
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