An API can be easy to discover and still be hard to run.
OpenAPI 3.1.1 solves a narrow but important problem: it gives teams a language-agnostic way to describe an HTTP API so tools can generate docs, client code, and tests from the same contract. That is useful. But a spec only tells you what the interface looks like. It does not tell you who owns changes, who approves breaking edits, or how operators will know a dependency has drifted.
That gap is where integrations become brittle. Google’s API design guidance leans on resource-oriented design and standard methods because consistency reduces cognitive load. RFC 9700 does the same kind of work for OAuth 2.0 security: it updates earlier guidance because the threat model keeps changing. The lesson is not “write more documentation.” It is that the contract and the control model have to age together.
A practical test: if a field name changes, a scope is retired, or a rate limit tightens, can the support team explain the impact before users feel it? If not, the integration is only half designed. The code may be valid, but the service is not yet operationally complete.
For workplace systems, that usually means treating APIs as managed dependencies, not just technical interfaces. The contract matters. So does the answer to who carries it after launch.