Resource API

The Resource API provides a generic, Kubernetes-shaped model for platform objects and custom resource kinds. This section documents its current capabilities, limitations, and intended role in the evolution of Rise’s typed API.

Current capabilities

Resources have an apiVersion, kind, metadata, spec, and status. The generic HTTP API exposes resource collections, individual objects, and status and finalizer subresources under /api/v1/resources/.

A ResourceDefinition registers a custom kind and its JSON Schema. A controller reconciles desired state with an external system, writes its own status, and uses finalizers to coordinate cleanup before deletion. These objects use the same resource storage semantics as built-in kinds.

The storage model includes optimistic concurrency through revisions, owner references, finalizer-gated deletion, and controller-owned status. Access to the HTTP API is evaluated through resource permissions; see the HTTP API reference for authorization and token details.

Intended extension model

The goal is to move functionality exposed by the typed API toward the generic resource model. An extension would define resource kinds and use a controller to reconcile their desired state with an external service. This provides a common model for defining, authorizing, observing, and deleting the objects managed by an integration.

Configuration for the existing project extension providers is documented under Extend.

Current limitations

• Controllers poll for changes; a watch or change-feed API is planned.
• List pagination and label/field selectors are planned.
• Writes target the storage version. Served versions do not provide automatic schema conversion; resource and controller authors manage schema migrations.

Detailed references

• Storage model — object storage, finalizers, deletion, garbage collection, and revision semantics.
• Custom resources — ResourceDefinition registration, schema validation, versioning, and controller ownership.
• HTTP API — resource paths, authorization, request and response envelopes, and subresource operations.
• JSON schemas — generated schemas for resource objects and metadata.