mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-12 20:16:29 +03:00
28 lines
2.2 KiB
Markdown
28 lines
2.2 KiB
Markdown
# Interface Selection
|
|
|
|
Choose the smallest interface that preserves the consumer job and domain semantics.
|
|
An API may use more than one style; record why each boundary exists.
|
|
|
|
| Style | Fits when | Design focus | Compatibility surface |
|
|
|---|---|---|---|
|
|
| REST/HTTP | Resource-oriented reads and broadly interoperable request/response | HTTP semantics, representations, cache and conditional behavior | Methods, media types, fields, defaults, status/error behavior |
|
|
| GraphQL | Consumers need shaped traversals across a governed graph | Schema ownership, query cost, nullability, resolver authority | Types, fields, arguments, enums/unions, query cost and generated clients |
|
|
| RPC | A named domain command is clearer than resource state transfer | Command intent, input/output schema, deadlines and side effects | Operation names, request/response fields, error model and client stubs |
|
|
| Event/message | Facts must reach independent consumers asynchronously | Event ownership, delivery and replay semantics | Topic/channel, envelope, schema, delivery and ordering guarantees |
|
|
| Webhook | A provider must notify a consumer over HTTP | Subscription, callback safety, verification and delivery contract | Registration, payload, signature profile, retries and disablement behavior |
|
|
| Streaming | Consumers need an ongoing sequence or bidirectional session | Session lifecycle, flow control, resume and ordering scope | Framing, cursors/checkpoints, backpressure, reconnect and retention behavior |
|
|
|
|
Ask before choosing:
|
|
|
|
- Who initiates interaction, and who owns the authoritative state or schema?
|
|
- Is the consumer querying current state, issuing a command, receiving a fact, or
|
|
maintaining a live view?
|
|
- What failures are tolerable: delay, duplicate, loss, reordering, or partial work?
|
|
- Which client types, networks, generated tools, intermediaries, and caching layers
|
|
participate?
|
|
- What must evolve independently, and what contract must remain stable?
|
|
|
|
Do not select GraphQL only to avoid endpoint design, events only for "real time," or
|
|
URL versions only because a semantic change is difficult. A style decision is a local
|
|
trade-off, not an organization-wide rule unless it belongs in an ADR.
|