This project is based on practical learnings from scaling the Gilt technology organization across code, people, teams, and practices. At the time we started on this project, Gilt had over 100 active committers, a distributed micro services architecture with over 300 independent applications, and significant revenue and traffic.

The idea for apidoc stems from our team's realization that, in order to continue iterating and growing, we needed a new approach to handle the complexity of a growing microservice architecture.

As developers, we were constantly building new APIs, spending a lot of time writing clients and learning the intricacies of services provided by other teams. By spending more time up front on API design, and using standardized client libraries, we could free up our time to focus on building the services and less time in the integration tasks.

We explored what was available on the market - trying different projects to hand write interfaces for a few systems we were actively building. We looked at protobufs, thrift, avro, swagger, apiary, raml and others before identifying our key requirements:

  • Incredibly nice clients w/ no dependencies - the developer experience using apidoc clients is amazing - we want developers to love apidoc clients so much they no longer want to write their own client libraries.
  • Zero runtime dependencies / changes in production code.
  • JSON: HTTP/JSON is everywhere. By focusing on this standard, we can ensure that the tooling we provide is available to all web developers - seamlessly including native application, web, and backend developers.
  • REST first: Specifically api.json starts with a list of resources instead of operations as we want to encourage the identification of REST resources as early as possible in the development process.
  • Simple documentation: Upload a JSON file and you have documentation. We want documentation to be first class, simple and immediate. Using apidoc just for documentation is one of our core intended use cases.
  • Simple and terse schema: We wanted a web developer to be able to learn the schema by looking at a few simple examples. We also are writing the JSON by hand and need it to be terse and clear.
  • No code annotations: we found that too many annotations made it difficult to see the code. Especially in a micro-services environment, we want to keep our applications simple and pure.
  • Compatibility with existing tools: We borrowed everything we could from other projects and thus where possible we adopted standards from existing work. We were heavily inspired by swagger in particular and support a subset of swagger 2.0 specs as input into apidoc (still very early and experimental).