API languages are in their infancy. API developers are pioneers, choosing the best technology for each individual job. Earlier in the year, InfoQ covered an active debate on Hacker News about API specification alternatives.
The community debate shows that there is no single standard. API developers are actively using API Blueprint, RAML, and Swagger. Together, as a community, developers are defining the standards that will be used in the future.
InfoQ recently had the opportunity to talk to Jakub Nesetril, creator of the API Blueprint project and CEO of Apiary.
InfoQ: Can you explain the purpose of API Blueprint and its genesis?
Jakub Nestril: API Blueprint was born before RAML during the early Swagger days. Swagger was really similar to WADL and API Blueprint focused on being a simple, human readable and writable format.
Apiary platform was born during a weekend hackathon. When we were choosing a format we looked at all the options out there and found the alternatives really complex and we’ve been working over the next year to build out a really simple, compelling way to describe APIs.
InfoQ: The current version of API Blueprint is format 1A8 and was released a few weeks ago. Could you describe the main enhancements in this version?
JN: We focused on referencing, reuse and strong support for markdown native data typing. A big part of 1A8 is MSON which is markdown syntax object notation, a simplified version of JSON Schema. We tried to do a flavor that is very human readable and writable to simplify the life of developers. It’s 100% compatible with JSON Schema and actually compiles into JSON Schema on the backend.
InfoQ: How do you manage the release of specification changes and all the related tooling?
JN: We release the language first. It’s fully MIT licensed and we already have many contributors. We communicate the language updates several months in advance, update the parser first and then give ourselves at Apiary a couple of weeks to catch up.
InfoQ: What is your reaction to the recent change of sponsorship for Swagger, passing from Reverb to SmartBear?
JN: I welcome the new sponsorship from SmartBear and also welcome that Tory Tam stays involved with the Swagger project. The attention that the design-first approach to API development is now getting is great for us and for all API vendors
Apiary has always been an API tooling company - API Blueprint is our means towards delivering simplicity to development and product teams. We’re excited to see the other formats converging onto the same world-view - it helps us bring the API industry out of the stone-age of building internal one-off tools.
I've had a great relationship with Ole (Smartbear’s CTO) in the the past so I look forward to keeping this good relationship going forward.
InfoQ: There are discussions in the Swagger community about the best open governance model for the project moving forward. Can you tell us more about the API Blueprint governance model, its organization, level of openness and effectiveness?
JN: API Blueprint has been the most open source description format by having a flexible MIT license. We’ve been intentionally developing an open community and communicating the intended changes and evolution of the language for many months in advance of the release. We generally accept all community contributions that we get.
I haven't seen our current model as a bottleneck, but Swagger has had more large cross-vendor involvement, so maybe they need a more formal governance model. I think Smartbear is still trying to figure out “how open is open” in the Swagger governance context. We’re happy to participate on moving the whole API community forward.
InfoQ: RAML introduced the notion of traits and types to describe cross-cutting API aspects such as query parameters for pagination on collection resources. Does API Blueprint have similar capabilities?
JN: Yes, although we take a slightly different approach. The way people use traits is as a shortcut to help with consistency across an API, but it complicates the authoring process by having to mentally project all sorts of inheritance rules and overlapping declarations.
API Blueprint is focused on easy creation and consumption. And so, rather than trying to support complex architectural design patterns within itself, we have separated the architectural oversight into an API Blueprint Assertion language which allows our large customers to define their API style guides across the whole company programmatically. We introduced this as part as Apiary for Enterprise last fall and we are in the process of rolling it out more broadly.
InfoQ: What are the main strengths of API Blueprint compared to Swagger v2.0 and RAML v0.8?
JN: API Blueprint is the most human friendly format and we found it to be very popular with developers, product managers, documentation writers and architects. The biggest strength is bringing all of this to the same table.
InfoQ: Do you think one of these API languages will eventually win or is there room for several related languages? What are the chances of API Blueprint to become a de facto standard for API definitions?
JN: I think what I find exciting is that I see the languages converging. When we started out with API Blueprint, Swagger was very young and to me complex, but it made big advances towards simplicity, like we did with a large open source community, so I can imagine that both languages will converge. If not, I'm sure that there will be strong interoperability between them.
InfoQ: What are the most interesting community projects that you have seen emerge around API Blueprint? Can you describe a few of them?
JN: A very popular open source doc renderer, Aglio, was built by a developer at AWS. Developers at Lonely Planet have also built Vigia, an API Blueprint adapter for RSpec. Paw - an awesome native API client for OS X has strongly integrated API Blueprint. There’s obviously a whole breath of community tools, from plugins for SublimeText or Atom or Vim to integrations into Postman and cURL etc - many more than we can mention here. You can see the complete list on API Blueprint web site.
InfoQ: What does API Blueprint offer for client SDK generation?
JN: A lot in fact. We generate code stubs for 15 languages as part of our API documentation, which makes starting out with API consumption very quick.
More broadly, all the documentation formats have a great chance to autoconfigure an SDK client at runtime rather than statically generating it. The big advantages come with the API change lifecycle and with hypermedia. I think long term the right answer is runtime configuration rather than generation. You can see the future on our universal, auto-configurable SDK for iOS called Hyperdrive - it’s really awesome. You can compile it into your iOS app, link to an API Blueprint at runtime - and never having to change it anymore. Through API Blueprint it understands your API, knows how to navigate it, knows how to serialize/deserialize API calls, how to validate them etc. For mobile developers this is going to be huge.
InfoQ: What is your view on the usefulness of hypermedia APIs? Is API Blueprint supporting this style of APIs or planning to do so?
JN: I think hypermedia APIs have a big potential to simplify API versioning and more importantly handling of change. API Blueprint probably has the best hypermedia support out there, but it’s only scratching the surface of the full potential and we have great ideas about how much better it could be. Some of the key people behind hypermedia like Mark Foster or Stephen Mizell are working at Apiary right now and you can be sure they’re not sitting idle. :)
InfoQ: What are the main development workflows that you observed based on API Blueprint?
JN: The workflow we are most excited about is when API backend team and API consumer team co-design and co-develop both sides of the API in parallel. That’s why we built a mock server in Apiary from day one. We’re also the first ones to bring TDD to the API workflow - when you define an API Blueprint today, you can use Dredd to help you implement the API correctly or just to keep your API documentation in check. Sometimes I joke that we bring code-coverage to your API documentation.
InfoQ: Do you see an evolution from API code-first towards API definition-first workflows?
JN: Yes, very much so. We’ve been there from day one, and it’s very gratifying to see more and more people every day understand the value of definition-first. The transition to definition-first is fueled by the growing value of the tools derived from those definitions. We see that growing every month and it’s only going to increase.
InfoQ: Do you have any other thoughts to share with InfoQ readers about API Blueprint’s future?
JN: We are really excited about the recent addition of MSON and data structures, the workflow it enables in API testing and imminent additions like strong authentication support and reuse.
There are over 100,000 developers using API Blueprint so it’s safe to say it’s here to stay just as markdown is.
Note: This article is part of a part of a four-part series on API languages. For more information and perspectives on API languages, check out these articles:
- Community Debates API Specification Alternatives
- Swagger Founder Makes Commitment to Keep Project Open
- RAML Founder Talks About the API Industry: Governance, Technology, and Acquisitions
Disclaimer: the author of this article works for Restlet, a web API platform provider supporting several web API languages including Swagger and RAML