A managed service is wire-compatible with an open interface - what does that compatibility usually not cover?

## The seam you do not have to build The cheapest portable seam is the one somebody else already made. A provider operates the service - it patches, scales and backs it up - but the service answers a **protocol or API defined outside that provider**, one that other implementations also answer. Your application speaks that protocol through an ordinary client library, and the same library, pointed at a different implementation, works. Nothing in the application knows which platform is underneath. That is genuinely valuable and genuinely narrow. Compatibility is a claim about the **data path**: the requests a running workload issues and the responses it gets back. Everything on the **control path** - how the service comes into existence and how it is operated - lies outside the standard, so it remains the provider's own design. ## The edges compatibility does not cover | Concern | Covered by the open interface? | Who actually defines it | |---|---|---| | Request and response format on the data path | yes | the standard | | Client library and call semantics | mostly | the standard | | Creating, sizing and upgrading the service | no | the platform | | Authenticating the caller | rarely | the platform's identity model | | Backup format, retention and restore | no | the platform | | Metrics, logs and their names | no | the platform | | Quotas, throttling thresholds and errors at the limit | no | the platform | | Which optional parts of the standard exist | partly | the implementation | Reading the middle column downwards *is* the answer. A migration between two compatible implementations leaves application code alone and asks you to rebuild everything that surrounds it: the provisioning automation, the access policy, the backup and restore procedure, the dashboards and alerts, and the retry policy that was tuned against the old implementation's limits. ## Three distinct kinds of gap 1. **Surface gaps.** Standards have optional parts, and implementations pick subsets. A call your workload depends on may not exist at all, or may exist and return a reduced result - a filter that is ignored, a field that is always empty, a batch operation capped lower than you assumed. 2. **Behaviour gaps.** The same call with the same arguments can differ in latency, in throughput under concurrency, in when a write becomes visible to a following read, in how a very large payload is handled, and in how a partial failure is reported. None of that appears in the interface, and all of it appears in your production behaviour. This is where compatible services most often disappoint. 3. **Limit gaps.** Every implementation has quotas and throttles - maximum object size, requests per second against one key, connection counts - and both their values and their error behaviour at the boundary differ. Code written against a generous implementation quietly acquires assumptions it never wrote down. ## What to do about it - **Establish the subset you actually rely on** and write it down: the calls, the optional features, the payload sizes, the consistency assumption and the error codes you handle. A subset that is recorded can be checked against another implementation in an afternoon; one that lives in the code cannot. - **Exercise a second implementation early**, not at migration time, with your own traffic shapes rather than a demo. A compatibility matrix from either side tells you which calls *exist*; only your workload tells you which ones *behave*. - **Keep the control path thin and replaceable.** Provisioning, access policy and telemetry wiring are the parts that will be rewritten; the less bespoke they are, the cheaper that rewrite is. - **Budget the edges instead of denying them.** A compatible managed service is often exactly the right buy, because the operating work it removes is continuous and real. The defect is not choosing it - the defect is recording it as `portable` in a plan and then budgeting nothing for what compatibility never covered. ## Why teams get this wrong Compatibility is advertised on the data path because that is the part that demonstrates well: a client library proves it in an afternoon. The edges stay invisible until the move. Nobody notices that their provisioning was written against one platform's management API until a second one is needed, and nobody notices that their retry policy assumes a particular throttling shape until it meets a different one. The habit that prevents the surprise is to ask of every compatibility claim: compatible for **which calls**, and compatible in **which properties**. Treat the answer as a subset, always - and note that implementations differ in how much of the standard they cover, so the subset has to be established against each one rather than assumed once.