diff --git a/content/docs/api/client-sdk.mdx b/content/docs/api/client-sdk.mdx index b0aff91571..6ed4f6ef5a 100644 --- a/content/docs/api/client-sdk.mdx +++ b/content/docs/api/client-sdk.mdx @@ -87,7 +87,7 @@ When you call `client.connect()`, the client: // connect() resolves with the discovery manifest — capture the return value const discovery = await client.connect(); -console.log(discovery.version); // "1.0.0" +console.log(discovery.version); // the serving artifact's version console.log(discovery.environment); // "development" // Check if a service is available before using it diff --git a/content/docs/api/index.mdx b/content/docs/api/index.mdx index 1de637be5c..d509e666d7 100644 --- a/content/docs/api/index.mdx +++ b/content/docs/api/index.mdx @@ -100,7 +100,7 @@ Schema reference: [API](/docs/references/api) ## Discovery -The discovery endpoint is the entry point for all clients. It returns the API version, available routes, service capabilities, and per-service status. +The discovery endpoint is the entry point for all clients. It returns the serving artifact's version, available routes, service capabilities, and per-service status. ### `GET /api/v1` (and `GET /api/v1/discovery`) @@ -114,7 +114,7 @@ the dispatcher cedes the route to it, so a single owner answers it (ADR-0076 D11 **Response**: ```json { - "version": "v1", + "version": "", "apiName": "ObjectStack API", "routes": { "data": "/api/v1/data", @@ -140,6 +140,8 @@ the dispatcher cedes the route to it, so a single owner answers it (ADR-0076 D11 } ``` +`version` is the **serving artifact's** version, not the API version: the `OS_RUNTIME_VERSION` stamp when a deployment injects one, otherwise the resolved version of the package that built the response. It carried the configured `api.version` (the `v1` path segment) until #11292 removed that override — the API version is still readable here, as the base path every `routes` entry is prefixed with. + Disabled/uninstalled route keys (e.g. `auth`, `analytics`, `workflow`) are omitted from `routes` entirely rather than set to `null`; check `services` to tell "not installed" apart from "installed but not yet mounted here." The sample above shows a minimal install: `analytics` reports `unavailable` and advertises no route until `@objectstack/service-analytics` registers the engine — the dispatcher then also mounts `/api/v1/analytics/*` (the routes are capability-conditional; an uninstalled capability answers 404 for every method). `metadata` is reported from whatever implementation fills its slot, so the sample's `available` is the `MetadataPlugin` case (a persisted `sys_metadata` registry). A stack running the kernel's in-memory fallback instead reports `status: "degraded"` with a `message` naming what is missing and what to install. `handlerReady` is `true` either way: `/api/v1/meta` is served by the protocol, so the route is mounted whichever registry sits behind it. diff --git a/content/docs/protocol/kernel/http-protocol.mdx b/content/docs/protocol/kernel/http-protocol.mdx index 21e6f3d25e..438c90e3ce 100644 --- a/content/docs/protocol/kernel/http-protocol.mdx +++ b/content/docs/protocol/kernel/http-protocol.mdx @@ -43,7 +43,7 @@ Host: api.acme.com **Response:** ```json { - "version": "v1", + "version": "", "name": "ObjectStack API", "apiName": "ObjectStack API", "environment": "development", @@ -78,9 +78,14 @@ Host: api.acme.com Three things about this body are worth stating explicitly: -- **`version` is the configured API version, not a product version.** The handler - overwrites the protocol's value with `api.version` — the same string that forms the - path segment (`"v1"`). It is never a semantic version like `2.1.0`. +- **`version` is the serving artifact's version, not the configured API version.** The + handler serves the protocol builder's own value — the `OS_RUNTIME_VERSION` stamp when a + deployment injects one, otherwise the resolved `@objectstack/metadata-protocol` version + — so a semantic version is the normal answer. It used to be overwritten with + `api.version` (the same `"v1"` string that forms the path segment); #11292 removed that + override, because the identity field then answered with the path segment the caller had + just typed to get there. The API version has not left this document: every `routes` + entry below is prefixed with the mounted base path, which is built from `api.version`. - **`name` is canonical; `apiName` is a deprecated alias with the same value.** Both are emitted today so clients pinned to the old spelling keep working; `apiName` is removed in **protocol 18** (#4828). Read `name`. @@ -126,7 +131,7 @@ Host: api.acme.com "success": true, "data": { "name": "ObjectOS", - "version": "1.0.0", + "version": "", "environment": "production", "routes": { "data": "/api/v1/data", @@ -160,10 +165,13 @@ Host: api.acme.com } ``` -`name` and `version` are the dispatcher's own build identity, not your app's name — they -are fixed strings, so do not display them as the deployment's title. `locale` is derived -from the registered i18n service (`getDefaultLocale()` / `getLocales()`); with no i18n -service it degrades to `{ "default": "en", "supported": ["en"], "timezone": "UTC" }`. +`name` and `version` are the dispatcher's own build identity, not your app's name — do +not display them as the deployment's title. `name` is a fixed string; `version` is the +serving artifact's version — the `OS_RUNTIME_VERSION` stamp when a deployment injects one, +otherwise the resolved `@objectstack/runtime` version (#10993), never a hardcoded literal. +`locale` is derived from the registered i18n service (`getDefaultLocale()` / +`getLocales()`); with no i18n service it degrades to +`{ "default": "en", "supported": ["en"], "timezone": "UTC" }`. `environment` is **derived from** `NODE_ENV`, not the raw value — the field is an enum (`production` / `sandbox` / `development`), so out-of-enum spellings are mapped rather