Services and APIs#

Design a service around stable operations and effects, then let planning choose whether each edge is local, process-bound, remote, or externally managed.

Define the operation completely#

An operation contract includes:

• nominal request and response schemas;
• declared domain faults;
• read, write, disclosure, deletion, and external effects;
• deadline and cancellation behavior;
• idempotency, deduplication, and outcome-query support;
• authority and identity requirements;
• ordering, consistency, and transactional expectations;
• observation, audit, privacy, and retention obligations.

Do not encode HTTP status codes, queue names, database tables, or cloud product names unless they are genuinely part of the domain contract.

Idempotency and outcome queries#

Every mutating operation declares how a repeated or uncertain attempt is resolved:

• idempotency caller_key(...) binds deduplication to a caller-supplied key with an explicit window;
• idempotency provider_key(...) is valid only when the selected provider actually proves the guarantee;
• outcome query <Operation> names the read that reveals the result of an attempt whose response was lost; and
• an operation with neither is honestly non-idempotent and cannot be auto-retried after dispatch.

A duplicate delivery returns the original result rather than performing a second effect. When the outcome is genuinely unknown, reconcile through the declared outcome query instead of reissuing the mutation. The OCS contract carries these declarations, and the communication model keeps them distinct from transport-level retry.

Compose before distributing#

Components call owned operations. A service groups coherent operations and lifecycle behavior, but does not imply a remote endpoint. Planning can inline a small implementation, host it in a process, place it behind a network boundary, or bind it to an external provider.

Remote placement adds codecs, authentication, routing, discovery, encryption, timeouts, retry, backpressure, partial failure, and cost. The plan shows every added requirement and why it exists.

Project protocols at the edge#

HTTP, RPC, event, streaming, and messaging interfaces are projections of the operation contract. A protocol profile defines mappings for paths or methods, frames, faults, metadata, identity, cancellation, deadlines, compatibility, and evidence.

A transport success is not a domain success. A domain fault remains distinct from denial, timeout, cancellation, incompatibility, provider failure, and an unknown effect outcome.

Versioning and directional compatibility#

Compatible revisions can negotiate only within the released closure. A breaking semantic change creates an explicit new contract revision and a planned coexistence or cutover. The plan identifies every producer, consumer, stored value, client, route, and workflow affected.

Aliases can improve human use only when the lock resolves them to one exact owner-qualified identity. Plans, approvals, receipts, and automation retain the exact identity.

Compatibility is directional and owner-validated: the destination owner states which prior revisions a new revision still serves and for which fields, frames, and faults. A new required field, a narrowed variant set, or a changed fault is not made compatible by keeping the name and @1 lane. The OCS contract is the language-neutral package that carries the resulting schemas, faults, and operation shapes across generated clients and boundaries, and each projection records its supported subset and loss.

Test the boundary you claim#

Use direct contract tests for implementations, schema and codec conformance for projections, protocol tests for adapters, fault injection for delivery and timeouts, and full root tests for composed behavior. A provider claim is valid only for its tested revision, configuration, target, and environment.

Common mistakes#

Protocol leakage. Routes, HTTP status codes, queue names, database tables, and cloud product names belong in the protocol or realization projection, not in the operation contract. Keeping them out lets the same meaning be inlined, hosted in a process, reached over the network, or bound to an external provider without rewriting the domain.

Reading transport success as domain success. A 200 OK, a completed dispatch, or an accepted enqueue says nothing about the domain result. A domain fault remains distinct from denial, timeout, cancellation, incompatibility, provider failure, and an unknown effect outcome; see the failure model.

Assuming idempotency. Retry is safe only within a declared idempotency and outcome-query contract. An operation without one must suspend or reconcile, not blindly repeat.

Example#

Illustrative end-product syntax declares meaning before protocol:

operation Orders.GetOrder@1
    accepts GetOrderRequest
    returns Order
    faults OrderNotFound
    effect read

See operations and outcomes for every clause and the intended result vocabulary.

Executable evidence#

The checked-in ParcelHub project declares, implements, checks, and invokes the Orders Get/Place/Cancel operations, including typed domain faults and idempotent placement:

cargo test -p parcelhub --all-targets --locked
one check --workspace systems/system/idl/examples/parcelhub --offline

Follow the typed service recipe for the source and lifecycle walkthrough, and read contracts and components for how a service groups owned operations.

See communication and check, test, and invoke, then follow the typed service recipe.