API Design and description is more than just a technical interface contract between machines. Apiary's Co-Founder and CEO Jakub Nesetril points out that the real consumer of an API description is the developer, with all the concerns of engagement, usability and communication that entails. We spoke with Jakub recently about Apiary's approach to API design and emerging API tools and workflows.
InfoQ: Jakub, you recently presented at the API Strategy conference on a panel about best practices in API design. You mentioned there that there is no "one way to build an API." Can you tell us a bit about that philosophy and how it relates to what Apiary is doing?
JN: Historically the API has been seen as the interface between two computer programs. In reality, the API is an interface between developers - real people. If developers don't know how to use your API, then that's it, game-over - your project will fail.
APIs (and software interface design in general) behaves very similarly to UI design: it is influenced by fashion cycles, it differs by cultural background (in programming that means usually culture around languages and frameworks), it's easy to be very opinionated about it but nobody can agree what the right design is.
Just as it would be silly to search for "one and only" UI design, there is no one canonical API design. But there are techniques to mitigate the inherent subjectiveness. As we saw with evolution of the user interface, a focus on user-centered design and the user experience emerged as central to design in the last decade. We need to bring that same approach to API development, centered around agile, rapid iteration, and tight feedback loop with customers and stakeholders.
InfoQ: There are a number of API description standards vying for adoption including your own API Blueprint. Some of these are based on JSON, or Markdown or YAML or even XML. Do you have any views on what approach is best? What made you choose Markdown over something else?
JN: XML, JSON and YAML formats were around when we started Apiary, and we tried hard NOT to invent anything new. We felt strongly that those languages are far too complex, especially if you bring other roles to the table—a technical documentation writer, or your API consumer—to participate. They also tend to be really awkward for carrying large amount of human-readable text, something that good API documentation tends to have.
We searched for a format that's popular among developers, can be used to write structured data and also paragraphs of prose. Our goal was to find something very human-readable and human-writable. We wanted that it is understood by technical and non-technical people alike. For years markdown has been used by virtually every open-source project out there, and is the core of GitHub Pages and Jekyll publishing systems. Developers have used these for years.
InfoQ: Some developers advocate hypermedia as an alternative to contract-based API development. This might have an obvious answer, but what are your thoughts on API contracts vs non-contracts?
JN: We see Hypermedia as having a lot of potential, but as of now still limited traction. Hypermedia struggles with adoption. If adopted widely we could see the consumption side of APIs shift dramatically, however the utility of contracts is still there the validation and automated testing and tooling they enable. Without better tooling support the situation is likely to stay as it is. However a lot of smart people are trying to improve the the tooling, so we'll see where this goes in the future.
InfoQ:You recently launched the Dredd tool for automated testing of API implementation against a blueprint. You seem to be working toward a specific workflow with respect to API design and development. Can you describe that?
JN: Software development has shifted over the last decade with a preference on agile iterations over the traditional, static waterfall design. With agile we saw things like automated testing, code coverage and continuous integration energe. But when it comes to APIs and the interface contracts, we're still partying like it's 1999 ‐ upfront design, monumental development projects, obsolete documentation, no code coverage, no continuous integration. At Apiary we're working to change that.
Dredd is a good example of that. All developers know that tedious, manual and error‐prone tasks should be automated. Ensuring that your API documentation remains current is precisely one of those. Everybody hates maintaining documentation. With Dredd we're bringing code-coverage to your API documentation, in a way that's fundamentally compatible with any continuous integration provider out there.
InfoQ: Developer engagement seems to be the "secret sauce" for API adoption and success. What are the key things that everyone is missing in terms of developer engagement?
JN: The focus on usability and empowerment ‐ it's still rare. If you look at ALL the successful API projects (and developer-focused companies in general) they all have a strong brand, great user experience in their products and they empower their users to do things they didn't think were possible before. It's not rocket science, but it is much harder to recreate. Empathy for user needs is not an easy emotion to train or acquire. That's why a lot of Apiary's design is focused on bringing people together: the API designers, the API developers, the API consumers - to create an environment where it's easy for them to collaborate.
InfoQ: You have 25,000 APIs under development with apiary do you have any plans for leveraging that position, such as an API marketplace or repository?
JN: That number is growing every week, so it's hard to keep a track of it. We are at 35k and climbing. As recently as a year ago, industry analysts were seriously discussing if there are 50,000 or 80,000 APIs worldwide in total. Now we know that the real number is much, much bigger. Despite Apiary's massive growth in just the past 12 months, the majority of the industry is using in‐house, custom‐made tools. There's plenty of space to grow into.
We focus single‐handedly on what we do best ‐ building tools that empower developers. The idea of an API marketplace or a repository looks attractive on the surface, but we just haven't seen anything yet that would truly add value.
Apiary Inc. is headquartered in San Francisco with engineering operations in Prague, Czech Republic. It was founded by Jakub Nesetril and Jan Moravec, and opened a public beta of its innovative API design platform at end of 2012. To date Apiary has gathered over 35,000 APIs, making it the largest collection of APIs worldwide. Among it's early customers are developer portals of Akamai or GoodData. We recently spoke to Jakub Nesetril about API design, description, tools and testing.
