Thursday, October 28, 2021
tl;dr - Simplify API development by generating your OpenAPI specs that automatically follow your API Design Guide. Produce 100x more consistent and conforming APIs with 1/10th the work ... for every development team. Ok, ok. So your company has decided to standardize on OpenAPI with a contract-first approach. Awesome. But job done? Hardly. Does your company already have an API Design Guide to ensure your developers produce uniform APIs that your customers will love? If so, that's a great next step. OpenAPI can be used to implement pretty much any HTTP-based API design. But this leaves the unpleasant task of translating from the API Design Guide to a conforming OpenAPI spec to your developers. Newer alternatives to REST APIs such as GraphQL and GRPC benefit significantly from removing a lot of this design and development friction from developers. They hide the infra plumbing and expose tooling at an abstraction level that developers care about. In this talk, we'll describe how we've bridged this gap for REST APIs at Confluent. Rather than asking overworked developers to read and internalize the myriad details from our (quite lengthy) API Design Guide, we created an internal DSL and CLI tool to generate OpenAPI specs that follow our API Design Guide. Even better than API linting, OpenAPI generation results in the most consistent API designs. In turn, this simplifies API adoption and expansion for our customers, while reducing the workload for our overburdened engineers. Win-win!