Why Choose API Builder?

There are a few very different foundational reasons for which teams choose API Builder as their tool of choice for API Management. We know there are a number of different tools available in the market; teams often use API Builder either as their only API tool or as a complementary tool to their existing solutions.

Here we've collected a list of the common reasons why teams adopt API Builder.

  • Very, very high quality generated clients: Teams that use API Builder end up relying 100% on the generated clients - ie. the developers STOP writing and managing their own client SDKs freeing up time to focus on product improvements. In practice this is only possible because developers love to use the clients from API Builder. The reason this is possible is because API Builder focuses end to end on only supporting features that ensure the client SDKs themselves are high quality.
  • Resource centric: API Builder is resource first - instead of defining an operation explicitly, you define resources and then expose operations on that resource. This is hugely important for today's technology landscape given the rise of other resource oriented tooling (e.g. graphQL) where having high quality metadata on available resources is a huge help.
  • Simple service specification: API Builder at its core separates the notion of the input format (e.g. api.json, swagger, avro) from the service description (service.json). This is a huge advantage as regardless of input format, the service specification can be fully expanded and complete. This separation enables API Builder to easily accept new input formats AND makes it very easy to fully parse a service (just download the service spec and use directly). The service spec is verbose and complete - perfect for machines. (If you are familiar with CQRS you will recognize that pattern here.)
  • Simple input format: The default api.json format is simple for humans to write. It is JSON, but more than that it is approachable by a novice and designed to be both simple and easy. There is no need to understand $ref or oneOf or other constructs which which new developers often struggle. Instead, developers can look at existing examples and very easily copy/modify for their new application.
  • Great validation: When you upload a new version of an API, extensive validation checks are run to ensure the internal consistency of your API. These checks are among the most comprehensive you can find anywhere - ensuring that all types, names, etc are internally valid. The development of this validation is one of the key steps to ensuring that ultimately the generated clients themselves are very robust and simple - and it starts by catching inconsistencies when the API specification is defined.
  • Integrated tooling: API Builder itself offers a comprehensive REST API (the entire https://app.apibuilder.io/ website runs on the API Builder API) which means it is simple to automate any tasks as needed into your developer workflows. Teams have even written linters that enforce naming standards and conventions in the API itself, running as part of their suites of continuous integration tests. Note also the simple to use CLI - many teams never actually even use the user interface of API Builder on a daily basis given the completeness of the API and CLI tooling.
  • Easy to add code generators: Code generators in API Builder are themselves REST services which accept a service description (in JSON) and essentially return a string. Teams often write their own code generators - even small disposable ones - to systematically solve problems in an automated fashion.
  • Testability of clients: With generated mock clients built from the same interface definition, teams can rely on mocks when building automated tests - and further use the provided mock clients to override only the specific features needed for a given test.
  • Multiple input formats Teams are free to author their specifications in multiple IDLs (swagger, avro, etc.), and it is straightforward to introduce new input formats into API Builder.
  • First class support for union types: Union types - a type that itself is constrained to be one of a known set of types - are first class and simple to use in API Builder. This is a powerful feature that enables developers to maintain simpler APIs by empowering them, for example, to create new types vs. continually adding optional fields to existing types.
  • Discovery: Free hosting of all services at https://app.apibuilder.io/, including both private and public projects makes service discovery easy within a company.
  • Versioning: API Builder records every single change to every API - presenting a list of safe and potentially breaking changes. Teams often use these lists to include in their own release notes. For example, here is the history of changes to the API Builder API itself.