Operations & Resources
Relevant source files
The following files were used as context for generating this wiki page:
Operations represent individual actions a caller can perform against a service, while Resources group these operations into logical entities that model the service's domain. The Crucible project uses these constructs to generate API documentation, client SDKs, and a machine-readable describe.json contract.
Operations define specific HTTP methods, URIs, and data structures for requests and responses. Resources provide a lifecycle-oriented view, mapping CRUD actions (Create, Read, Update, Delete, List) to specific operations.
Operations Architecture
Operations act as the fundamental units of the service interface. Each operation contains metadata defining its wire protocol, authentication requirements, and data bindings.
Operation Components
An operation consists of several key elements:
- HTTP Metadata: Defines the method (e.g.,
GET,POST) and the URI template. - Bindings: Maps model members to specific locations in the HTTP request, such as path labels, query parameters, headers, or the request body.
- Authorization: Specifies the permissions a caller must hold to execute the operation.
- Shapes: References input and output structures that define the data contract.
Sources: crates/crucible-codegen-common/src/describe.rs:260-310, crates/crucible-codegen-docs/src/markdown.rs:564-620
Request and Response Flow
When an operation executes, data flows through configured bindings. Path labels are replaced with values, query parameters are appended to the URI, and headers are injected.
This diagram illustrates how Crucible maps structured input shapes to HTTP request components and decodes responses back into output shapes.
Sources: crates/crucible-codegen-common/src/describe.rs:343-400, crates/crucible-codegen-docs/runtime/explorer.js:330-360
Resource Management
Resources organize operations into a hierarchy that mirrors the domain model. A resource typically identifies a specific entity type and manages its lifecycle through standard operations.
Resource Lifecycle
Crucible supports a standard set of lifecycle slots for resources. These slots allow generators to identify which operations perform specific CRUD functions.
| Lifecycle Slot | Purpose |
|---|---|
create | Creates a new instance of the resource. |
read | Retrieves a specific resource instance. |
update | Modifies an existing resource instance. |
delete | Removes a resource instance. |
list | Returns a collection of resource instances. |
put | Idempotently creates or replaces a resource. |
Sources: crates/crucible-codegen-common/src/describe.rs:218-225, crates/crucible-codegen-docs/src/markdown.rs:188-205, crates/crucible-codegen-docs/runtime/explorer.js:524-535
Resource Hierarchy
Resources can contain child resources, creating a tree structure. For example, an Organization resource might contain multiple Graph resources.
This diagram shows the relationship between resources and operations, where operations are bound to resources to provide context.
Sources: crates/crucible-codegen-docs/tests/golden/permissions-internal/llms.txt:13-25, crates/crucible-codegen-docs/runtime/explorer.js:154-170
Operation Metadata and Constraints
Operations carry additional properties that govern behavior such as idempotency, pagination, and error handling.
Key Operation Properties
| Property | Description |
|---|---|
readonly | Indicates the operation does not modify state and is safe to retry. |
idempotent | Indicates the operation can be called multiple times with the same effect. |
idempotencyToken | A member used by SDKs to automatically ensure exactly-once execution. |
pagination | Defines the tokens and member paths used to walk through large result sets. |
sender | Identifies a third party that calls the operation and signs the request. |
Sources: crates/crucible-codegen-common/src/describe.rs:276-290, crates/crucible-codegen-docs/src/markdown.rs:627-645, crates/crucible-codegen-docs/runtime/explorer.js:555-580
Error Handling
Operations define a list of modeled errors. Each error maps a specific HTTP status code and fault type (Client or Server) to a data structure. Crucible documentation generates tables explaining which errors can occur and whether they are retryable.
Sources: crates/crucible-codegen-common/src/describe.rs:430-450, crates/crucible-codegen-docs/src/markdown.rs:456-500
Client SDK Generation
Code generators translate the Operation and Resource models into native language constructs.
- Go: Generates a client struct where operations are methods. Paginated operations receive specific Paginator types.
- C#: Generates a sealed class with asynchronous (
Async) and synchronous methods. Resources provide context for fully qualified references in XML documentation. - JavaScript (Explorer): Uses the
describe.jsoncontract to dynamically render an interactive API reference that can build and send requests.
Sources: crates/crucible-codegen-go/src/lib.rs:13-35, crates/crucible-codegen-csharp/src/lib.rs:47-75, crates/crucible-codegen-docs/runtime/explorer.js:540-600
Operations and resources form the core of the Crucible service model. Operations define the "how" of API interaction, while Resources define the "what," allowing the system to generate consistent documentation and highly capable client libraries.