Zum Hauptinhalt springen

REST reference

REST is the system of record for federation mutations and many reads. GraphQL composes queries on top; it does not replace these paths.

Spec filefederation-v3.yaml (OpenAPI 3.1)
Contract2026-05-plexon-federation-v3
AuthSee Auth

This page explains the registered operations in the SDK OpenAPI for this docs build. Some product routes exist in runtime specs but are not fully in the OpenAPI registry yet — those are listed under Coverage gaps.

Common headers​

X-Service-Secret: <product secret>
X-Plexon-Contract-Version: 2026-05-plexon-federation-v3
X-Plexon-User-Id: <viewer user id> # required on viewer-scoped routes

Build them with buildFederationHeaders from @chbrdk/plexon-federation.

Operations in this OpenAPI build​

MethodPathPurposeAuth notes
POST/api/auth/validate-credentialsCheck login materialControlled; do this from a server
PUT/api/platform/provisioning/projects/{platformProjectId}Upsert Collection mirror into a productService; body validated by upsert schema
POST/api/platform/provisioning/metron-project-originExample origin create (product-first)Service; other products follow the same pattern with their path
GET/api/platform/provisioning/accessible-collectionsCollections the viewer may openService + viewer id
GET/POST…/api/platform/provisioning/collections/{platformProjectId}/membersMembershipService + appropriate actor
…/api/platform/provisioning/collections/{platformProjectId}/invitesInvitesService + appropriate actor
POST/api/services/usage/eventsUsage eventsService

Exact request/response schemas: download the YAML or import the Zod schemas from the SDK — do not hand-roll parallel types.

Example — list accessible Collections​

curl -sS "${PLEXON_BASE}/api/platform/provisioning/accessible-collections" \
-H "X-Service-Secret: ${PLEXON_SERVICE_SECRET}" \
-H "X-Plexon-Contract-Version: 2026-05-plexon-federation-v3" \
-H "X-Plexon-User-Id: ${PLEXON_USER_ID}"

Example — upsert (Control Plane → product)​

Your product exposes the upsert URL from its capability descriptor. The Control Plane sends a PUT with Collection metadata. Validate with PlatformProjectUpsertRequestSchema, persist, return the upsert response schema.

Coverage gaps (honest)​

These areas have product/runtime specs or paths but are not fully represented as first-class operations in the OpenAPI download yet. Until they are, treat the linked behaviour as “follow the SDK when present; otherwise ask the DIC team / read the suite API spec your team shares”:

TopicStatus in this portal build
Viewer product catalogueDocumented in suite API specs; expand OpenAPI in a follow-up
Service profileSame
Notification feeds / visibilityWire types may exist in the SDK; OpenAPI coverage is catching up
System bannersRuntime + app chrome; OpenAPI follow-up

When a gap closes, this page and the YAML download update together.

Errors​

Prefer FederationErrorBodySchema for shared error shapes. Typical HTTP:

CodeMeaning
401Missing/invalid auth or actor
403Authenticated but not permitted
404Unknown Collection / resource
409 / 422Conflict or validation

What usually goes wrong​

SymptomFix
YAML and running server disagreePin SDK version; regenerate OpenAPI from the registry
Origin path 404You called another product’s origin URL — use your descriptor path
Members call works in staging UI but not from your appMissing viewer header or wrong Collection id

Next: GraphQL · TypeScript SDK · Onboarding recipe