Skip to content

http.md

Latest commit

 

History

History
34 lines (19 loc) · 2.63 KB

http.md

File metadata and controls

34 lines (19 loc) · 2.63 KB
Raw

HTTP API and OpenAPI

The public API at http://localhost:3000/api is served directly by Core. Standalone Core at http://localhost:3001 supports the same routes with or without /api. Plugin routes use /api/<namespace>/… on the common domain. Browsers use HttpOnly sessions; SDK/external applications use Bearer tokens.

Start with client setup, filters/pagination, relationship saves, and errors. See data for collection/search limits and access matrix for authorization.

The reference runs without a CDN. Request execution, external Swagger validation, and authorization persistence are disabled so browsing documentation does not mutate data.

Coverage

All static Core REST routes are listed. Key items/auth/settings operations include JSON contracts; others are explicitly x-contract-level:route-only, documenting method, path, path parameters, access, and source file without claiming full body/response schemas. Do not generate a complete SDK from this incomplete specification.

ALL /oauth/* is under x-delegated-routes. OIDC discovery supplies actual protocol endpoints. Dynamic plugin routes come from files/build indexes and are not automatically included in static Core OpenAPI.

Authentication and errors

Use Authorization: Bearer <accessToken>. Core access tokens are opaque; external-application OAuth tokens do not work here. Settings require a human and the relevant section grant. The Bearer security scheme describes transport, not sufficient permissions.

Typical statuses: 400 invalid input, 401 unauthenticated, 403 denied, 404 missing/not disclosed, 409 conflict, 429 rate limit, and 503 dependency unavailable. Response envelopes vary: auth token pairs are direct; items/users usually use data.

Core errors use { code, message, details, requestId }. Details is currently empty and excludes protected values/internal errors. Preserve requestId for diagnostics. Infrastructure may return a different error if Core is unreachable.

Collection schemas are dynamic. Successful create/update may return data:null without read grants. Large IDs/totals remain strings. SDK documentation describes the client contract.