History

1 The Problem

At Gilt, developers were constantly building new APIs and spending significant time writing client libraries and learning the intricacies of services owned by other teams. The integration cost was growing faster than the team.

The insight: by investing more time upfront in API design and using standardized generated client libraries, teams could focus on building services instead of integration work.

2 What We Evaluated

The team explored protobufs, thrift, avro, swagger, apiary, RAML, and others — hand-writing interfaces for systems actively being built. None fully met the requirements.

3 Key Requirements

• Clients developers love — Generated clients so good that developers stop writing their own. Zero runtime dependencies.
• JSON / HTTP first — The universal standard. By focusing on HTTP/JSON, the tooling is available to all web developers — native apps, web frontends, and backend services alike.
• Resource-centric — api.json starts with resources, not operations. This encourages identifying resources early and has proven valuable with resource-first approaches like GraphQL.
• Simple, terse schema — A web developer should learn the format by reading a few examples. Hand-written JSON that is clear and compact.
• Instant documentation — Upload a JSON file and documentation appears. Using API Builder purely for documentation is a core use case.
• No code annotations — Annotations clutter code. In a microservices environment, applications should stay simple and pure.
• Compatible with existing tools — Standards are borrowed from existing projects wherever possible, making API Builder fully compatible with frameworks like Swagger and Avro.