plugin-rest-api.mdx

title	Plugin Rest Api
description	Plugin Rest Api protocol schemas

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

\{

"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"]

\}

]

\}

\}

**Source:** `packages/spec/src/api/plugin-rest-api.zod.ts`

TypeScript Usage

import { ErrorHandlingConfig, OpenApiGenerationConfig, RequestValidationConfig, ResponseEnvelopeConfig, RestApiEndpoint, RestApiPluginConfig, RestApiRouteCategory, RestApiRouteRegistration, ValidationMode } from '@objectstack/spec/api';
import type { ErrorHandlingConfig, OpenApiGenerationConfig, RequestValidationConfig, ResponseEnvelopeConfig, RestApiEndpoint, RestApiPluginConfig, RestApiRouteCategory, RestApiRouteRegistration, 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

---

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

---

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

---

ValidationMode

Allowed Values

• strict
• permissive
• strip

---