API Specifications Conference 2021

We all want to provide a great developer experience when we build APIs. But while we have helpful industry patterns and practices, we lack tools that can guide us toward a good design and away from complexity.

We want to avoid complexity whenever we can. A complex API is harder to change. It’s harder to reason about, test, and consume. Complexity creates opportunity for bugs and breaking changes that arise when we least expect it. If we had the right tools to highlight complexity, we could make better choices about ways to avoid it.

In this talk, we’ll look at different ways to understand the complexity of an API design. We’ll look at schemas in an OpenAPI document to measure schema entropy—a calculation of all possible variations of a schema that can direct us toward problematic areas of a design. We’ll also assess other characteristics of schemas that can hint at complexity.

We’ll use these measurements to discuss ways to insulate client code from unforeseen issues in an API. And we’ll also see how API providers can use these insights to safely evolve their APIs.