Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/docs/api/client-sdk.mdx
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
6 changes: 4 additions & 2 deletions content/docs/api/index.mdx
Original file line numberDiff line numberDiff line change
Expand Up@@ -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`)

Expand All@@ -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": "<the serving artifact's version>",
"apiName": "ObjectStack API",
"routes": {
"data": "/api/v1/data",
Expand All@@ -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.
Expand Down
26 changes: 17 additions & 9 deletions content/docs/protocol/kernel/http-protocol.mdx
Original file line numberDiff line numberDiff line change
Expand Up@@ -43,7 +43,7 @@ Host: api.acme.com
**Response:**
```json
{
"version": "v1",
"version": "<the serving artifact's version>",
"name": "ObjectStack API",
"apiName": "ObjectStack API",
"environment": "development",
Expand DownExpand Up@@ -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`.
Expand DownExpand Up@@ -126,7 +131,7 @@ Host: api.acme.com
"success": true,
"data": {
"name": "ObjectOS",
"version": "1.0.0",
"version": "<the serving artifact's version>",
"environment": "production",
"routes": {
"data": "/api/v1/data",
Expand DownExpand Up@@ -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
Expand Down
Loading