---
title: Plugin Rest Api
description: Plugin Rest Api protocol schemas
---

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

REST API Plugin Protocol

Defines the schema for REST API plugins that register Discovery, Metadata,

Data CRUD, Batch, and Permission routes with the HTTP Dispatcher.

This plugin type implements Phase 2 of the API Protocol implementation plan,

providing standardized REST endpoints with:

- Request validation middleware using Zod schemas

- Response envelope wrapping with BaseResponseSchema

- Error handling using ApiErrorSchema

- OpenAPI documentation auto-generation

Features:

- Route registration for core API endpoints

- Automatic schema-based validation

- Standardized request/response envelopes

- OpenAPI/Swagger documentation generation

Architecture Alignment:

- Salesforce: REST API with metadata and data CRUD

- Microsoft Dynamics: Web API with entity operations

- Strapi: Auto-generated REST endpoints from schemas

@example Plugin Manifest

```typescript

\{

"name": "rest_api",

"version": "1.0.0",

"type": "server",

"contributes": \{

"routes": [

\{

"prefix": "/api/v1/discovery",

"service": "metadata",

"methods": ["getDiscovery"],

"middleware": [

\{ "name": "response_envelope", "type": "transformation", "enabled": true \}

]

\},

\{

"prefix": "/api/v1/meta",

"service": "metadata",

"methods": ["getMetaTypes", "getMetaItems", "getMetaItem", "saveMetaItem"],

"middleware": [

\{ "name": "auth", "type": "authentication", "enabled": true \},

\{ "name": "request_validation", "type": "validation", "enabled": true \}

]

\},

\{

"prefix": "/api/v1/data",

"service": "data",

"methods": ["findData", "getData", "createData", "updateData", "deleteData"]

\}

]

\}

\}

```

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

## TypeScript Usage

```typescript
import { ErrorHandlingConfig, HandlerStatus, OpenApiGenerationConfig, RequestValidationConfig, ResponseEnvelopeConfig, RestApiEndpoint, RestApiPluginConfig, RestApiRouteCategory, RestApiRouteRegistration, RouteCoverageEntry, RouteCoverageReport, ValidationMode } from '@objectstack/spec/api';
import type { ErrorHandlingConfig, HandlerStatus, OpenApiGenerationConfig, RequestValidationConfig, ResponseEnvelopeConfig, RestApiEndpoint, RestApiPluginConfig, RestApiRouteCategory, RestApiRouteRegistration, RouteCoverageEntry, RouteCoverageReport, ValidationMode } from '@objectstack/spec/api';

// Validate data
const result = ErrorHandlingConfig.parse(data);
```

---

## ErrorHandlingConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable standardized error handling |
| **includeStackTrace** | `boolean` | ✅ | Include stack traces in error responses |
| **logErrors** | `boolean` | ✅ | Log errors to system logger |
| **exposeInternalErrors** | `boolean` | ✅ | Expose internal error details in responses |
| **includeRequestId** | `boolean` | ✅ | Include requestId in error responses |
| **includeTimestamp** | `boolean` | ✅ | Include timestamp in error responses |
| **includeDocumentation** | `boolean` | ✅ | Include documentation URLs for errors |
| **documentationBaseUrl** | `string` | optional | Base URL for error documentation |
| **customErrorMessages** | `Record<string, string>` | optional | Custom error messages by error code |
| **redactFields** | `string[]` | optional | Field names to redact from error details |


---

## HandlerStatus

### Allowed Values

* `implemented`
* `stub`
* `planned`


---

## OpenApiGenerationConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable automatic OpenAPI documentation generation |
| **version** | `Enum<'3.0.0' \| '3.0.1' \| '3.0.2' \| '3.0.3' \| '3.1.0'>` | ✅ | OpenAPI specification version |
| **title** | `string` | ✅ | API title |
| **description** | `string` | optional | API description |
| **apiVersion** | `string` | ✅ | API version |
| **outputPath** | `string` | ✅ | URL path to serve OpenAPI JSON |
| **uiPath** | `string` | ✅ | URL path to serve documentation UI |
| **uiFramework** | `Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'elements'>` | ✅ | Documentation UI framework |
| **includeInternal** | `boolean` | ✅ | Include internal endpoints in documentation |
| **generateSchemas** | `boolean` | ✅ | Auto-generate schemas from Zod definitions |
| **includeExamples** | `boolean` | ✅ | Include request/response examples |
| **servers** | `Object[]` | optional | Server URLs for API |
| **contact** | `Object` | optional | API contact information |
| **license** | `Object` | optional | API license information |
| **securitySchemes** | `Record<string, Object>` | optional | Security scheme definitions |


---

## RequestValidationConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable automatic request validation |
| **mode** | `Enum<'strict' \| 'permissive' \| 'strip'>` | ✅ | How to handle validation errors |
| **validateBody** | `boolean` | ✅ | Validate request body against schema |
| **validateQuery** | `boolean` | ✅ | Validate query string parameters |
| **validateParams** | `boolean` | ✅ | Validate URL path parameters |
| **validateHeaders** | `boolean` | ✅ | Validate request headers |
| **includeFieldErrors** | `boolean` | ✅ | Include field-level error details in response |
| **errorPrefix** | `string` | optional | Custom prefix for validation error messages |
| **schemaRegistry** | `string` | optional | Schema registry name to use for validation |


---

## ResponseEnvelopeConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable automatic response envelope wrapping |
| **includeMetadata** | `boolean` | ✅ | Include meta object in responses |
| **includeTimestamp** | `boolean` | ✅ | Include timestamp in response metadata |
| **includeRequestId** | `boolean` | ✅ | Include requestId in response metadata |
| **includeDuration** | `boolean` | ✅ | Include request duration in ms |
| **includeTraceId** | `boolean` | ✅ | Include distributed traceId |
| **customMetadata** | `Record<string, any>` | optional | Additional metadata fields to include |
| **skipIfWrapped** | `boolean` | ✅ | Skip wrapping if response already has success field |


---

## RestApiEndpoint

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method for this endpoint |
| **path** | `string` | ✅ | URL path pattern (e.g., /api/v1/data/:object/:id) |
| **handler** | `string` | ✅ | Protocol method name or handler identifier |
| **category** | `Enum<'discovery' \| 'metadata' \| 'data' \| 'batch' \| 'permission' \| 'analytics' \| 'automation' \| 'workflow' \| 'ui' \| 'realtime' \| 'notification' \| 'ai' \| 'i18n'>` | ✅ | Route category |
| **public** | `boolean` | ✅ | Is publicly accessible without authentication |
| **permissions** | `string[]` | optional | Required permissions (e.g., ["data.read", "object.account.read"]) |
| **summary** | `string` | optional | Short description for OpenAPI |
| **description** | `string` | optional | Detailed description for OpenAPI |
| **tags** | `string[]` | optional | OpenAPI tags for grouping |
| **requestSchema** | `string` | optional | Request schema name (for validation) |
| **responseSchema** | `string` | optional | Response schema name (for documentation) |
| **timeout** | `integer` | optional | Request timeout in milliseconds |
| **rateLimit** | `string` | optional | Rate limit policy name |
| **cacheable** | `boolean` | ✅ | Whether response can be cached |
| **cacheTtl** | `integer` | optional | Cache TTL in seconds |
| **handlerStatus** | `Enum<'implemented' \| 'stub' \| 'planned'>` | optional | Handler implementation status: implemented (default if omitted), stub, or planned |


---

## RestApiPluginConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **enabled** | `boolean` | ✅ | Enable REST API plugin |
| **basePath** | `string` | ✅ | Base path for all API routes |
| **version** | `string` | ✅ | API version identifier |
| **routes** | `Object[]` | ✅ | Route registrations |
| **validation** | `Object` | optional | Request validation configuration |
| **responseEnvelope** | `Object` | optional | Response envelope configuration |
| **errorHandling** | `Object` | optional | Error handling configuration |
| **openApi** | `Object` | optional | OpenAPI documentation configuration |
| **globalMiddleware** | `Object[]` | optional | Global middleware stack |
| **cors** | `Object` | optional | CORS configuration |
| **performance** | `Object` | optional | Performance optimization settings |


---

## RestApiRouteCategory

### Allowed Values

* `discovery`
* `metadata`
* `data`
* `batch`
* `permission`
* `analytics`
* `automation`
* `workflow`
* `ui`
* `realtime`
* `notification`
* `ai`
* `i18n`


---

## RestApiRouteRegistration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **prefix** | `string` | ✅ | URL path prefix for this route group |
| **service** | `string` | ✅ | Core service name (metadata, data, auth, etc.) |
| **category** | `Enum<'discovery' \| 'metadata' \| 'data' \| 'batch' \| 'permission' \| 'analytics' \| 'automation' \| 'workflow' \| 'ui' \| 'realtime' \| 'notification' \| 'ai' \| 'i18n'>` | ✅ | Primary category for this route group |
| **methods** | `string[]` | optional | Protocol method names implemented |
| **endpoints** | `Object[]` | optional | Endpoint definitions |
| **middleware** | `Object[]` | optional | Middleware stack for this route group |
| **authRequired** | `boolean` | ✅ | Whether authentication is required by default |
| **documentation** | `Object` | optional | Documentation metadata for this route group |


---

## RouteCoverageEntry

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **path** | `string` | ✅ | Full URL path (e.g. /api/v1/analytics/query) |
| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method (GET, POST, etc.) |
| **category** | `Enum<'discovery' \| 'metadata' \| 'data' \| 'batch' \| 'permission' \| 'analytics' \| 'automation' \| 'workflow' \| 'ui' \| 'realtime' \| 'notification' \| 'ai' \| 'i18n'>` | ✅ | Route category |
| **handlerStatus** | `Enum<'implemented' \| 'stub' \| 'planned'>` | ✅ | Handler status |
| **service** | `string` | ✅ | Target service name |
| **healthCheckPassed** | `boolean` | optional | Whether the health check probe succeeded |


---

## RouteCoverageReport

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **timestamp** | `string` | ✅ | ISO 8601 timestamp |
| **adapter** | `string` | ✅ | Adapter name (e.g. "hono", "express", "nextjs") |
| **summary** | `Object` | ✅ |  |
| **entries** | `Object[]` | ✅ | Per-endpoint coverage entries |


---

## ValidationMode

### Allowed Values

* `strict`
* `permissive`
* `strip`


---

