---
title: Registry
description: Registry protocol schemas
---

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

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

```typescript

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

\}

\}

```

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

## TypeScript Usage

```typescript
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 |

---


---

