Skip to content

Commit 6ce592b

Browse files
hotlonghotlong
committed
Add JSON schema definitions for API and server configurations
- Introduced `GeneratedEndpoint.json` for defining generated API endpoints. - Added `MetadataEndpointsConfig.json` to configure metadata endpoint settings. - Created `RestApiConfig.json` for REST API configuration options. - Implemented `RestServerConfig.json` to encapsulate server-level configurations. - Added `RouteGenerationConfig.json` for route generation settings. - Introduced shared configurations: `CorsConfig.json`, `HttpMethod.json`, `RateLimitConfig.json`, and `StaticMount.json`. - Developed system configurations including `HttpServerConfig.json`, `MiddlewareConfig.json`, and related types. - Added event and status definitions with `ServerEvent.json`, `ServerEventType.json`, and `ServerStatus.json`.
1 parent 6c5d33e commit 6ce592b

80 files changed

Lines changed: 2372 additions & 3011 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎content/docs/references/api/endpoint.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ const result = ApiEndpointSchema.parse(data);
6161

6262
| Property | Type | Required | Description |
6363
| :--- | :--- | :--- | :--- |
64-
| **enabled** | `boolean` | optional | |
65-
| **windowMs** | `number` | optional | Time window in milliseconds |
66-
| **maxRequests** | `number` | optional | Max requests per window |
64+
| **enabled** | `boolean` | optional | Enable rate limiting |
65+
| **windowMs** | `integer` | optional | Time window in milliseconds |
66+
| **maxRequests** | `integer` | optional | Max requests per window |
6767

‎content/docs/references/api/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ This section contains all protocol schemas for the api layer of ObjectStack.
1818
<Card href="./odata" title="Odata" description="Source: packages/spec/src/api/odata.zod.ts" />
1919
<Card href="./protocol" title="Protocol" description="Source: packages/spec/src/api/protocol.zod.ts" />
2020
<Card href="./realtime" title="Realtime" description="Source: packages/spec/src/api/realtime.zod.ts" />
21+
<Card href="./rest-server" title="Rest Server" description="Source: packages/spec/src/api/rest-server.zod.ts" />
2122
<Card href="./router" title="Router" description="Source: packages/spec/src/api/router.zod.ts" />
2223
<Card href="./view-storage" title="View Storage" description="Source: packages/spec/src/api/view-storage.zod.ts" />
2324
<Card href="./websocket" title="Websocket" description="Source: packages/spec/src/api/websocket.zod.ts" />

‎content/docs/references/api/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
"odata",
1212
"protocol",
1313
"realtime",
14+
"rest-server",
1415
"router",
1516
"view-storage",
1617
"websocket"

‎content/docs/references/api/rest-server.mdx‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
title: Rest Server
3+
description: Rest Server protocol schemas
4+
---
5+
6+
# Rest Server
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/api/rest-server.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { BatchEndpointsConfigSchema, CrudEndpointPatternSchema, CrudEndpointsConfigSchema, CrudOperationSchema, EndpointRegistrySchema, GeneratedEndpointSchema, MetadataEndpointsConfigSchema, RestApiConfigSchema, RestServerConfigSchema, RouteGenerationConfigSchema } from '@objectstack/spec/api';
16+
import type { BatchEndpointsConfig, CrudEndpointPattern, CrudEndpointsConfig, CrudOperation, EndpointRegistry, GeneratedEndpoint, MetadataEndpointsConfig, RestApiConfig, RestServerConfig, RouteGenerationConfig } from '@objectstack/spec/api';
17+
18+
// Validate data
19+
const result = BatchEndpointsConfigSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## BatchEndpointsConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **maxBatchSize** | `integer` | optional | Maximum records per batch operation |
31+
| **enableBatchEndpoint** | `boolean` | optional | Enable POST /data/:object/batch endpoint |
32+
| **operations** | `object` | optional | Enable/disable specific batch operations |
33+
| **defaultAtomic** | `boolean` | optional | Default atomic/transaction mode for batch operations |
34+
35+
---
36+
37+
## CrudEndpointPattern
38+
39+
### Properties
40+
41+
| Property | Type | Required | Description |
42+
| :--- | :--- | :--- | :--- |
43+
| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method |
44+
| **path** | `string` | ✅ | URL path pattern |
45+
| **summary** | `string` | optional | Operation summary |
46+
| **description** | `string` | optional | Operation description |
47+
48+
---
49+
50+
## CrudEndpointsConfig
51+
52+
### Properties
53+
54+
| Property | Type | Required | Description |
55+
| :--- | :--- | :--- | :--- |
56+
| **operations** | `object` | optional | Enable/disable operations |
57+
| **patterns** | `Record<string, object>` | optional | Custom URL patterns for operations |
58+
| **dataPrefix** | `string` | optional | URL prefix for data endpoints |
59+
| **objectParamStyle** | `Enum<'path' \| 'query'>` | optional | How object name is passed (path param or query param) |
60+
61+
---
62+
63+
## CrudOperation
64+
65+
### Allowed Values
66+
67+
* `create`
68+
* `read`
69+
* `update`
70+
* `delete`
71+
* `list`
72+
73+
---
74+
75+
## EndpointRegistry
76+
77+
### Properties
78+
79+
| Property | Type | Required | Description |
80+
| :--- | :--- | :--- | :--- |
81+
| **endpoints** | `object[]` | ✅ | All generated endpoints |
82+
| **total** | `integer` | ✅ | Total number of endpoints |
83+
| **byObject** | `Record<string, object[]>` | optional | Endpoints grouped by object |
84+
| **byOperation** | `Record<string, object[]>` | optional | Endpoints grouped by operation |
85+
86+
---
87+
88+
## GeneratedEndpoint
89+
90+
### Properties
91+
92+
| Property | Type | Required | Description |
93+
| :--- | :--- | :--- | :--- |
94+
| **id** | `string` | ✅ | Unique endpoint identifier |
95+
| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>` | ✅ | HTTP method |
96+
| **path** | `string` | ✅ | Full URL path |
97+
| **object** | `string` | ✅ | Object name (snake_case) |
98+
| **operation** | `Enum<'create' \| 'read' \| 'update' \| 'delete' \| 'list'> \| string` | ✅ | Operation type |
99+
| **handler** | `string` | ✅ | Handler function identifier |
100+
| **metadata** | `object` | optional | |
101+
102+
---
103+
104+
## MetadataEndpointsConfig
105+
106+
### Properties
107+
108+
| Property | Type | Required | Description |
109+
| :--- | :--- | :--- | :--- |
110+
| **prefix** | `string` | optional | URL prefix for metadata endpoints |
111+
| **enableCache** | `boolean` | optional | Enable HTTP cache headers (ETag, Last-Modified) |
112+
| **cacheTtl** | `integer` | optional | Cache TTL in seconds |
113+
| **endpoints** | `object` | optional | Enable/disable specific endpoints |
114+
115+
---
116+
117+
## RestApiConfig
118+
119+
### Properties
120+
121+
| Property | Type | Required | Description |
122+
| :--- | :--- | :--- | :--- |
123+
| **version** | `string` | optional | API version (e.g., v1, v2, 2024-01) |
124+
| **basePath** | `string` | optional | Base URL path for API |
125+
| **apiPath** | `string` | optional | Full API path (defaults to `{basePath}`/`{version}`) |
126+
| **enableCrud** | `boolean` | optional | Enable automatic CRUD endpoint generation |
127+
| **enableMetadata** | `boolean` | optional | Enable metadata API endpoints |
128+
| **enableBatch** | `boolean` | optional | Enable batch operation endpoints |
129+
| **enableDiscovery** | `boolean` | optional | Enable API discovery endpoint |
130+
| **documentation** | `object` | optional | OpenAPI/Swagger documentation config |
131+
| **responseFormat** | `object` | optional | Response format options |
132+
133+
---
134+
135+
## RestServerConfig
136+
137+
### Properties
138+
139+
| Property | Type | Required | Description |
140+
| :--- | :--- | :--- | :--- |
141+
| **api** | `object` | optional | REST API configuration |
142+
| **crud** | `object` | optional | CRUD endpoints configuration |
143+
| **metadata** | `object` | optional | Metadata endpoints configuration |
144+
| **batch** | `object` | optional | Batch endpoints configuration |
145+
| **routes** | `object` | optional | Route generation configuration |
146+
147+
---
148+
149+
## RouteGenerationConfig
150+
151+
### Properties
152+
153+
| Property | Type | Required | Description |
154+
| :--- | :--- | :--- | :--- |
155+
| **includeObjects** | `string[]` | optional | Specific objects to generate routes for (empty = all) |
156+
| **excludeObjects** | `string[]` | optional | Objects to exclude from route generation |
157+
| **nameTransform** | `Enum<'none' \| 'plural' \| 'kebab-case' \| 'camelCase'>` | optional | Transform object names in URLs |
158+
| **overrides** | `Record<string, object>` | optional | Per-object route customization |
159+

content/docs/references/auth/connector.mdx renamed to content/docs/references/auth/http.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
2-
title: Connector
3-
description: Connector protocol schemas
2+
title: Http
3+
description: Http protocol schemas
44
---
55

6-
# Connector
6+
# Http
77

88
<Callout type="info">
9-
**Source:** `packages/spec/src/auth/connector.zod.ts`
9+
**Source:** `packages/spec/src/auth/http.zod.ts`
1010
</Callout>
1111

1212
## TypeScript Usage

‎content/docs/references/data/index.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,12 @@ description: Complete reference for all data protocol schemas
88
This section contains all protocol schemas for the data layer of ObjectStack.
99

1010
<Cards>
11+
<Card href="./data-engine" title="Data Engine" description="Source: packages/spec/src/data/data-engine.zod.ts" />
1112
<Card href="./dataset" title="Dataset" description="Source: packages/spec/src/data/dataset.zod.ts" />
1213
<Card href="./document" title="Document" description="Source: packages/spec/src/data/document.zod.ts" />
14+
<Card href="./driver" title="Driver" description="Source: packages/spec/src/data/driver.zod.ts" />
15+
<Card href="./driver-nosql" title="Driver Nosql" description="Source: packages/spec/src/data/driver-nosql.zod.ts" />
16+
<Card href="./driver-sql" title="Driver Sql" description="Source: packages/spec/src/data/driver-sql.zod.ts" />
1317
<Card href="./external-lookup" title="External Lookup" description="Source: packages/spec/src/data/external-lookup.zod.ts" />
1418
<Card href="./field" title="Field" description="Source: packages/spec/src/data/field.zod.ts" />
1519
<Card href="./filter" title="Filter" description="Source: packages/spec/src/data/filter.zod.ts" />

‎content/docs/references/data/meta.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
{
22
"title": "Data Protocol",
33
"pages": [
4+
"data-engine",
45
"dataset",
56
"document",
7+
"driver",
8+
"driver-nosql",
9+
"driver-sql",
610
"external-lookup",
711
"field",
812
"filter",

‎content/docs/references/integration/connector.mdx‎

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Connector protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { AuthenticationSchema, ConflictResolutionSchema, ConnectorSchema, ConnectorStatusSchema, ConnectorTypeSchema, DataSyncConfigSchema, FieldTransformSchema, RateLimitConfigSchema, RateLimitStrategySchema, RetryConfigSchema, RetryStrategySchema, SyncStrategySchema, WebhookConfigSchema, WebhookEventSchema, WebhookSignatureAlgorithmSchema } from '@objectstack/spec/integration';
16-
import type { Authentication, ConflictResolution, Connector, ConnectorStatus, ConnectorType, DataSyncConfig, FieldTransform, RateLimitConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';
15+
import { AuthenticationSchema, ConflictResolutionSchema, ConnectorSchema, ConnectorStatusSchema, ConnectorTypeSchema, DataSyncConfigSchema, FieldTransformSchema, RateLimitStrategySchema, RetryConfigSchema, RetryStrategySchema, SyncStrategySchema, WebhookConfigSchema, WebhookEventSchema, WebhookSignatureAlgorithmSchema } from '@objectstack/spec/integration';
16+
import type { Authentication, ConflictResolution, Connector, ConnectorStatus, ConnectorType, DataSyncConfig, FieldTransform, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';
1717

1818
// Validate data
1919
const result = AuthenticationSchema.parse(data);
@@ -121,21 +121,6 @@ Connector type
121121

122122
---
123123

124-
## RateLimitConfig
125-
126-
### Properties
127-
128-
| Property | Type | Required | Description |
129-
| :--- | :--- | :--- | :--- |
130-
| **strategy** | `Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>` | optional | Rate limiting strategy |
131-
| **maxRequests** | `number` | ✅ | Maximum requests per window |
132-
| **windowSeconds** | `number` | ✅ | Time window in seconds |
133-
| **burstCapacity** | `number` | optional | Burst capacity |
134-
| **respectUpstreamLimits** | `boolean` | optional | Respect external rate limit headers |
135-
| **rateLimitHeaders** | `object` | optional | Custom rate limit headers |
136-
137-
---
138-
139124
## RateLimitStrategy
140125

141126
Rate limiting strategy

‎content/docs/references/integration/http.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Http
3+
description: Http protocol schemas
4+
---
5+
6+
# Http
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/integration/http.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { RateLimitConfigSchema } from '@objectstack/spec/integration';
16+
import type { RateLimitConfig } from '@objectstack/spec/integration';
17+
18+
// Validate data
19+
const result = RateLimitConfigSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## RateLimitConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **strategy** | `Enum<'fixed_window' \| 'sliding_window' \| 'token_bucket' \| 'leaky_bucket'>` | optional | Rate limiting strategy |
31+
| **maxRequests** | `number` | ✅ | Maximum requests per window |
32+
| **windowSeconds** | `number` | ✅ | Time window in seconds |
33+
| **burstCapacity** | `number` | optional | Burst capacity |
34+
| **respectUpstreamLimits** | `boolean` | optional | Respect external rate limit headers |
35+
| **rateLimitHeaders** | `object` | optional | Custom rate limit headers |
36+

‎content/docs/references/shared/http.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Http
3+
description: Http protocol schemas
4+
---
5+
6+
# Http
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/shared/http.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { CorsConfigSchema, RateLimitConfigSchema, StaticMountSchema } from '@objectstack/spec/shared';
16+
import type { CorsConfig, RateLimitConfig, StaticMount } from '@objectstack/spec/shared';
17+
18+
// Validate data
19+
const result = CorsConfigSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## CorsConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **enabled** | `boolean` | optional | Enable CORS |
31+
| **origins** | `string \| string[]` | optional | Allowed origins (* for all) |
32+
| **methods** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH' \| 'HEAD' \| 'OPTIONS'>[]` | optional | Allowed HTTP methods |
33+
| **credentials** | `boolean` | optional | Allow credentials (cookies, authorization headers) |
34+
| **maxAge** | `integer` | optional | Preflight cache duration in seconds |
35+
36+
---
37+
38+
## RateLimitConfig
39+
40+
### Properties
41+
42+
| Property | Type | Required | Description |
43+
| :--- | :--- | :--- | :--- |
44+
| **enabled** | `boolean` | optional | Enable rate limiting |
45+
| **windowMs** | `integer` | optional | Time window in milliseconds |
46+
| **maxRequests** | `integer` | optional | Max requests per window |
47+
48+
---
49+
50+
## StaticMount
51+
52+
### Properties
53+
54+
| Property | Type | Required | Description |
55+
| :--- | :--- | :--- | :--- |
56+
| **path** | `string` | ✅ | URL path to serve from |
57+
| **directory** | `string` | ✅ | Physical directory to serve |
58+
| **cacheControl** | `string` | optional | Cache-Control header value |
59+

0 commit comments

Comments
 (0)