Our Design Philosophy
SDKs are a critical interface for an API. We therefore put a lot of thought into what the developer experience should be:
- Type Safe - The SDKs we generate are fully typed.
- Human Readable - The SDKs we generate are easy for developers to read and debug.
- Batteries-Included - The SDKs we generate include everything from telemetry and retries to pagination.
- Fault Tolerant - Our generator is easy to use and outputs usable SDKs wherever possible. If we can't output a working SDK, we will validate your OpenAPI spec and alert you of the problems.
- Beyond OpenAPI - Our generator covers OpenAPI and can extend where OpenAPI falls short.
All the SDKs we generate are designed to be as idiomatic to their respective language as possible, while maintaining a common structure to allow for some familiarity in usage between them and an efficient, multi-language generation engine. Some of the design decisions we made are listed below:
- Each of the SDKs generally implements a base SDK class that contains the methods for each of the API endpoints defined in a spec.
- Where possible we generate fully typed models from the OpenAPI document and separate those models defined as components in the docs and those that are defined inline with operations.
- We annotate types with metadata when needed to determine behavior at runtime such as serialization, parameter names, etc. based on the configuration in the OpenAPI schema.
- We generate full packages for each language that are publishable to a package registry with little additional work, getting them into the hands of your end-users as quickly as possible.