rs2 / restspace

3.4 Patterns vs. facets (feature-detection over special-casing)

The store contract (3.3) is one example of a broader idea RS2 uses to keep clients simple: every mount declares a pattern (its conversation shape) and optional facets (capabilities within that shape). Clients drive by pattern and feature-detect facets — they never branch on a service's name.

Patterns: the conversation shape

A pattern tells a client how to talk to a mount. The discovery surface (GET /.well-known/rs2/services) reports one for every mount:

Pattern Shape
store The container/resource tree of 3.3 (file, data)
store-view / store-transform Authored-like-a-store, but executes specs on access (query, pipeline)
transform Processes a message into a response
api A service-specific endpoint set (e.g. auth)

A client that understands store can use any store mount. It doesn't need to know whether the bytes land on local disk, in memory, or (later) in S3 — that's an implementation detail behind the same conversation.

Facets: capabilities within a pattern

A facet is an optional capability a mount supports within its pattern. Two store mounts share the contract but may differ in facets:

{ "pattern": "store", "facets": ["range", "confirm-delete", "move"] }          // a file mount
{ "pattern": "store", "facets": ["schema", "patch", "echo", "confirm-delete"] } // a data mount

A client that wants byte ranges checks for the range facet; one that wants to PATCH checks for patch. If the facet is absent, it falls back — it does not hard-code "this is the file service, so it must support ranges."

Why this is worth caring about

  • Your clients survive change. When a new store (S3, SQL) is added, code written against store + facets works against it with no edits.
  • AI agents can drive the surface. The same metadata powers the agent surface and OpenAPI (9.1), so a tool can discover what a mount supports rather than being told out-of-band.
  • The runtime can add a service as a mode of an existing one. Static-site hosting isn't a new service — it's a file mount that declares the static-site facet. Variants are config (1.2), and facets are how clients notice them.

The takeaway for building clients: read the pattern, feature-detect the facets, never switch on the service name. Next we look at the mechanism that keeps custom code honest — capabilities and the sandbox.

← Previous: 3.3 The store pattern · Manual home · Next: 3.5 Capabilities and the sandbox →