Skip to content

registry.mdx

Latest commit

 

History

History
314 lines (200 loc) · 8.45 KB

registry.mdx

File metadata and controls

314 lines (200 loc) · 8.45 KB
Raw
title Registry
description 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

  • rest
  • graphql
  • odata
  • websocket
  • file
  • auth
  • metadata
  • plugin
  • webhook
  • rpc

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

  • error
  • priority
  • first-wins
  • last-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