ObjectStackRegistry
Registry protocol schemas
Unified API Registry Protocol
Provides a centralized registry for managing all API endpoints across different
API types (REST, GraphQL, OData, WebSocket, Auth, File, Plugin-registered).
This enables:
-
Unified API discovery and documentation (similar to Swagger/OpenAPI)
-
API testing interfaces
-
API governance and monitoring
-
Plugin API registration
-
Multi-protocol support
Architecture Alignment:
-
Kubernetes: Service Discovery & API Server
-
AWS API Gateway: Unified API Management
-
Kong Gateway: Plugin-based API Management
@example API Registry Entry
const apiEntry: ApiRegistryEntry = \{
id: 'customer_crud',
name: 'Customer CRUD API',
type: 'rest',
version: 'v1',
basePath: '/api/v1/data/customer',
endpoints: [...],
metadata: \{
owner: 'sales_team',
tags: ['customer', 'crm']
\}
\}Source: packages/spec/src/api/registry.zod.ts
TypeScript Usage
import { ApiDiscoveryQuery, ApiDiscoveryResponse, ApiEndpointRegistration, ApiMetadata, ApiParameter, ApiProtocolType, ApiRegistry, ApiRegistryEntry, ApiResponse, ConflictResolutionStrategy, HttpStatusCode, ObjectQLReference, SchemaDefinition } from '@objectstack/spec/api';
import type { ApiDiscoveryQuery, ApiDiscoveryResponse, ApiEndpointRegistration, ApiMetadata, ApiParameter, ApiProtocolType, ApiRegistry, ApiRegistryEntry, ApiResponse, ConflictResolutionStrategy, HttpStatusCode, ObjectQLReference, SchemaDefinition } from '@objectstack/spec/api';
// Validate data
const result = ApiDiscoveryQuery.parse(data);ApiDiscoveryQuery
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| type | Enum<'rest' | 'graphql' | 'odata' | 'websocket' | 'file' | 'auth' | 'metadata' | 'plugin' | 'webhook' | 'rpc'> | optional | Filter by API protocol type |
| tags | string[] | optional | Filter by tags (ANY match) |
| status | Enum<'active' | 'deprecated' | 'experimental' | 'beta'> | optional | Filter by lifecycle status |
| pluginSource | string | optional | Filter by plugin name |
| search | string | optional | Full-text search in name/description |
| version | string | optional | Filter by specific version |
ApiDiscoveryResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| apis | Object[] | ✅ | Matching API entries |
| total | integer | ✅ | Total matching APIs |
| filters | Object | optional | Applied query filters |
ApiEndpointRegistration
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | ✅ | Unique endpoint identifier |
| method | Enum<'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'> | optional | HTTP method |
| path | string | ✅ | URL path pattern |
| summary | string | optional | Short endpoint summary |
| description | string | optional | Detailed endpoint description |
| operationId | string | optional | Unique operation identifier |
| tags | string[] | ✅ | Tags for categorization |
| parameters | Object[] | ✅ | Endpoint parameters |
| requestBody | Object | optional | Request body specification |
| responses | Object[] | ✅ | Possible responses |
| rateLimit | Object | optional | Endpoint specific rate limiting |
| security | Record<string, string[]>[] | optional | Security requirements (e.g. [{"bearerAuth": []}]) |
| requiredPermissions | string[] | ✅ | Required RBAC permissions (e.g., "customer.read", "manage_users") |
| priority | integer | ✅ | Route priority for conflict resolution (0-1000, higher = more important) |
| protocolConfig | Record<string, any> | optional | Protocol-specific configuration for custom protocols (gRPC, tRPC, etc.) |
| deprecated | boolean | ✅ | Whether endpoint is deprecated |
| externalDocs | Object | optional | External documentation link |
ApiMetadata
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| owner | string | optional | Owner team or person |
| status | Enum<'active' | 'deprecated' | 'experimental' | 'beta'> | ✅ | API lifecycle status |
| tags | string[] | ✅ | Classification tags |
| pluginSource | string | optional | Source plugin name |
| custom | Record<string, any> | optional | Custom metadata fields |
ApiParameter
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Parameter name |
| in | Enum<'path' | 'query' | 'header' | 'body' | 'cookie'> | ✅ | Parameter location |
| description | string | optional | Parameter description |
| required | boolean | ✅ | Whether parameter is required |
| schema | Object | Object | ✅ | Parameter schema definition |
| example | any | optional | Example value |
ApiProtocolType
Allowed Values
restgraphqlodatawebsocketfileauthmetadatapluginwebhookrpc
ApiRegistry
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| version | string | ✅ | Registry version |
| conflictResolution | Enum<'error' | 'priority' | 'first-wins' | 'last-wins'> | ✅ | Strategy for handling route conflicts |
| apis | Object[] | ✅ | All registered APIs |
| totalApis | integer | ✅ | Total number of registered APIs |
| totalEndpoints | integer | ✅ | Total number of endpoints |
| byType | Record<string, Object[]> | optional | APIs grouped by protocol type |
| byStatus | Record<string, Object[]> | optional | APIs grouped by status |
| updatedAt | string | optional | Last registry update time |
ApiRegistryEntry
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | ✅ | Unique API identifier (snake_case) |
| name | string | ✅ | API display name |
| type | Enum<'rest' | 'graphql' | 'odata' | 'websocket' | 'file' | 'auth' | 'metadata' | 'plugin' | 'webhook' | 'rpc'> | ✅ | API protocol type |
| version | string | ✅ | API version (e.g., v1, 2024-01) |
| basePath | string | ✅ | Base URL path for this API |
| description | string | optional | API description |
| endpoints | Object[] | ✅ | Registered endpoints |
| config | Record<string, any> | optional | Protocol-specific configuration |
| metadata | Object | optional | Additional metadata |
| termsOfService | string | optional | Terms of service URL |
| contact | Object | optional | Contact information |
| license | Object | optional | License information |
ApiResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| statusCode | integer | Enum<'2xx' | '3xx' | '4xx' | '5xx'> | ✅ | HTTP status code |
| description | string | ✅ | Response description |
| contentType | string | ✅ | Response content type |
| schema | any | Object | optional | Response body schema |
| headers | Record<string, Object> | optional | Response headers |
| example | any | optional | Example response |
ConflictResolutionStrategy
Allowed Values
errorpriorityfirst-winslast-wins
HttpStatusCode
Union Options
This schema accepts one of the following structures:
Option 1
Type: integer
Option 2
Allowed Values: 2xx, 3xx, 4xx, 5xx
ObjectQLReference
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| objectId | string | ✅ | Object name to reference |
| includeFields | string[] | optional | Include only these fields in the schema |
| excludeFields | string[] | optional | Exclude these fields from the schema |
| includeRelated | string[] | optional | Include related objects via lookup fields |
SchemaDefinition
Union Options
This schema accepts one of the following structures:
Option 1
Static JSON Schema definition
Type: any
Option 2
Dynamic ObjectQL reference
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| $ref | Object | ✅ | Dynamic reference to ObjectQL object |