# 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.

## 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.

## Version meaning, not deployment trivia

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.

## 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.

## Example

Illustrative end-product syntax declares meaning before protocol:

```one
operation GetOrder@1
    input GetOrderRequest
    output Order
    faults OrderNotFound
    effect read(order)
```

See [communication](/one/model/communication) and
[check, test, and invoke](/one/lifecycle/check-test-invoke), then follow the
[typed service recipe](/one/examples/service).