From f37353ea164430ca866b98b327dfb523c7d6551e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 13:11:29 +0000 Subject: [PATCH 1/2] docs: retire the /graphql endpoint contract and protocol residue (#10832) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /graphql is not mounted. `packages/runtime/src/http-dispatcher.ts:2026` records its removal, there is no `createGraphQLDomain` among the domains registered at `http-dispatcher.ts:556-574`, and no `handleGraphQL` survives outside CHANGELOGs. Remove-vs-rewrite follows the 404/501 distinction in `packages/runtime/src/domains/unavailable.ts`: 404 = the route is not there; 501 = the route is there, the implementation is not. /graphql is in neither state, so it belongs in neither row of a catalog of servable routes. Deleted (the construct asserts a surface that does not exist): - `api/plugin-endpoints.mdx` — the whole `### GraphQL (/graphql)` section and its POST method/path table, plus GraphQL from the frontmatter enumeration. - `api/declarative-endpoints.mdx` — /graphql from the exemplar list pointing at that catalog; the two remaining examples are real mounted routes. - `protocol/diagram.mdx` — the `GQL[GraphQL]` node AND both its edges (`CLIENT --> GQL`, `GQL --> KERNEL`); mermaid materialises an undeclared node from a dangling edge, so deleting the declaration alone still renders a box. - `protocol/diagram.mdx` — GraphQL from the `src/api/` layer-table cell; that directory contains zero graphql files (re-measured). Rewritten (the surrounding claim is true; only the enumeration was wrong): - `protocol/diagram.mdx` sequence label → `HTTP Request (REST)`. - `protocol/kernel/lifecycle.mdx` → `Start HTTP server`, box width preserved. - `protocol/kernel/error-handling.mdx` → `(HTTP, WebSocket)`. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt --- content/docs/api/declarative-endpoints.mdx | 4 ++-- content/docs/api/plugin-endpoints.mdx | 8 +------- content/docs/protocol/diagram.mdx | 7 ++----- content/docs/protocol/kernel/error-handling.mdx | 2 +- content/docs/protocol/kernel/lifecycle.mdx | 2 +- 5 files changed, 7 insertions(+), 16 deletions(-) diff --git a/content/docs/api/declarative-endpoints.mdx b/content/docs/api/declarative-endpoints.mdx index 7437754615..f19ec9e545 100644 --- a/content/docs/api/declarative-endpoints.mdx +++ b/content/docs/api/declarative-endpoints.mdx @@ -12,8 +12,8 @@ publish gates serves real traffic as soon as the package is published. **This is not [Plugin Endpoints](/docs/api/plugin-endpoints).** That page is a *catalog of -built-in routes* the platform serves when a plugin is installed (`/auth`, `/automation`, -`/graphql`, …) — you call those, you do not write them. This page is about the endpoints +built-in routes* the platform serves when a plugin is installed (`/auth`, `/automation`, …) +— you call those, you do not write them. This page is about the endpoints **you declare**, which live under your own namespace and never overlap with that catalog. diff --git a/content/docs/api/plugin-endpoints.mdx b/content/docs/api/plugin-endpoints.mdx index f59d11cc1c..f8ba211b2a 100644 --- a/content/docs/api/plugin-endpoints.mdx +++ b/content/docs/api/plugin-endpoints.mdx @@ -1,6 +1,6 @@ --- title: Plugin Endpoints -description: REST endpoints that become available when the corresponding plugin is installed — auth, workflow, automation, views, realtime, notifications, AI, i18n, GraphQL, and file storage. +description: REST endpoints that become available when the corresponding plugin is installed — auth, workflow, automation, views, realtime, notifications, AI, i18n, and file storage. --- # Plugin Endpoints @@ -142,12 +142,6 @@ protocol `ai.chatStream` parses and owns message state for you. | GET | `/i18n/translations/:locale` | Get translation bundle | | GET | `/i18n/labels/:object/:locale` | Get field labels | -### GraphQL (`/graphql`) — Plugin Required - -| Method | Endpoint | Description | -|:-------|:---------|:------------| -| POST | `/graphql` | Execute GraphQL query/mutation | - ### File Storage (`/storage`) — Plugin Required Provided by `@objectstack/service-storage`, which registers these routes on the diff --git a/content/docs/protocol/diagram.mdx b/content/docs/protocol/diagram.mdx index b29a33c095..391db33be4 100644 --- a/content/docs/protocol/diagram.mdx +++ b/content/docs/protocol/diagram.mdx @@ -22,7 +22,7 @@ ObjectStack is composed of seven protocol layers that work together to form a co | **System (Kernel)** | `src/kernel/` | Manifest, Datasources, Plugins, Kernel | | **Automation** | `src/automation/` | Flows, Workflows, Triggers, Approvals | | **AI** | `src/ai/` | Agents, RAG Pipelines, Model Registry | -| **API** | `src/api/` | REST, GraphQL, WebSocket, Realtime | +| **API** | `src/api/` | REST, WebSocket, Realtime | | **Security** | `src/security/` | Permissions, Roles, Sharing, RLS | --- @@ -39,7 +39,6 @@ graph TB subgraph "API Layer" REST[REST Endpoints] - GQL[GraphQL] WS[WebSocket / Realtime] end @@ -92,12 +91,10 @@ graph TB %% Client to API CLIENT --> REST - CLIENT --> GQL CLIENT --> WS %% API references Data REST --> KERNEL - GQL --> KERNEL WS --> KERNEL %% Security enforced at Kernel @@ -160,7 +157,7 @@ sequenceDiagram participant D as Driver participant DB as Database - C->>API: HTTP Request (REST / GraphQL) + C->>API: HTTP Request (REST) API->>K: Parsed Operation K->>SEC: Check Permissions diff --git a/content/docs/protocol/kernel/error-handling.mdx b/content/docs/protocol/kernel/error-handling.mdx index c982e9af71..287e058530 100644 --- a/content/docs/protocol/kernel/error-handling.mdx +++ b/content/docs/protocol/kernel/error-handling.mdx @@ -7,7 +7,7 @@ import { AlertCircle, Bug, Shield, Info, AlertTriangle, XCircle, Radio, Zap } fr # Error Handling -The **Error Handling Protocol** defines standardized error codes, response formats, and debugging strategies across all ObjectStack APIs (HTTP, WebSocket, GraphQL). +The **Error Handling Protocol** defines standardized error codes, response formats, and debugging strategies across all ObjectStack APIs (HTTP, WebSocket). ## Why Standardized Errors Matter diff --git a/content/docs/protocol/kernel/lifecycle.mdx b/content/docs/protocol/kernel/lifecycle.mdx index 1be2aa439b..adcd840fde 100644 --- a/content/docs/protocol/kernel/lifecycle.mdx +++ b/content/docs/protocol/kernel/lifecycle.mdx @@ -67,7 +67,7 @@ The ObjectStack boot process follows a **strict order** to ensure dependencies a │ └─ Start event bus │ │ └─ Start job scheduler │ │ └─ Start audit logger │ -│ └─ Start HTTP/GraphQL servers │ +│ └─ Start HTTP server │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ From 451fe9215391678474477e8dfa5a35ba4de8cabe Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 13:30:45 +0000 Subject: [PATCH 2/2] docs(api): reflow the plugin-endpoints callout after the /graphql removal Keeps the em dash attached to the clause it belongs to instead of orphaning it at the start of a line, and refills the paragraph. No claim changes. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt --- content/docs/api/declarative-endpoints.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/api/declarative-endpoints.mdx b/content/docs/api/declarative-endpoints.mdx index f19ec9e545..bcd289eca3 100644 --- a/content/docs/api/declarative-endpoints.mdx +++ b/content/docs/api/declarative-endpoints.mdx @@ -12,9 +12,9 @@ publish gates serves real traffic as soon as the package is published. **This is not [Plugin Endpoints](/docs/api/plugin-endpoints).** That page is a *catalog of -built-in routes* the platform serves when a plugin is installed (`/auth`, `/automation`, …) -— you call those, you do not write them. This page is about the endpoints -**you declare**, which live under your own namespace and never overlap with that catalog. +built-in routes* the platform serves when a plugin is installed (`/auth`, `/automation`, …) — +you call those, you do not write them. This page is about the endpoints **you declare**, +which live under your own namespace and never overlap with that catalog. ## Which channel: `actions` or `apis`?