Over the last two years I’ve been working on a modern client generator for OpenAPI described APIs: project kiota. Kiota generates models and chained methods to allow developers to build requests for any REST API. The generated clients handle serialization, deserialization, authentication, retrying transient errors, following (or not) redirections and much more. Using a generated client saves developers from having to re-implement those aspects and enables them to focus on the core logic of the application.
Kiota relies on an OpenAPI description to understand what the API looks like and generate accurate clients. OpenAPI is a widely adopted standard across the industry which relies on JSON schema to describe the shape of the request and response bodies. JSON schema was originally designed as a data validation standard. Instead of describing “the data has a property foo of type string”, it describes “the data is valid if it contains a property foo of type string”. While this does not seem like a big difference at glance, there are many cases where this information is not prescriptive enough to describe type information for code generation.
Kiota is one of the many code generators out there, and while my team and I are working hard to make it one of the bests, all code generators would benefit from improvements in the standards. These improvements would also benefit API owners and API consumers as they would get more accurate clients without having to either handcraft them or fiddle with the API description.
As a community centered around REST APIs, I also think improving the client experience would help from a competitive aspect compared to other technologies like GraphQL or GRPC/protobuff.
I had the opportunity to present some of those challenges to the API specifications conference recently, and I thought publishing those in the open would help to keep the discussion going. I’ll publish a series of blog posts detailing each pattern, and when I have suggestions on how to address them, I’ll also include those. These posts are tagged to make them easier to find.