API Specifications Conference 2021

With a large, globally distributed engineering department of over 2,000 engineers, service discoverability and access to API documentation are important problems at Wayfair. Integrations between systems require close coordination and overhead, making these kinds of projects expensive and brittle. To address this problem, we sought to surface OpenAPI documentation in our Backstage Service Catalog.

We will discuss how over 175 API specifications are shared amongst teams at Wayfair. Our solution leverages the Kubernetes API, together with our home-grown tool for project generation, to programmatically surface OpenAPI files for inspection in Backstage. Backstage is a service catalog and developer portal recently released as open source by Spotify. Our work has had immediate service discoverability benefits for developers across our enterprise, with thousands of API doc page views since it launched. Of course, our work is never complete! As the solution rolled out, we discovered a lot of complexity in the space of surfacing API docs. We’ll discuss some of the problems we’ve encountered, as well as the solutions we’re trying, along the way. These problems include: whether to support code-first or schema-first development; how to store API schemas; and how to enforce versioning as part of the CI/CD pipeline. At the end of the talk, we want the audience to have a good understanding of the benefits of service discoverability, as well as the trade-offs inherent in making API specs discoverable.