---
title: Rest Server
description: Rest Server protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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

<Callout type="info">
**Source:** `packages/spec/src/api/rest-server.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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 /data/* with HTTP 401 |
| **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 |


---

