Posted on 01-31-2014
I am working through some deeper research into the world of API design, and specifically into the world of API definitions. This research involves talking to each of the leading providers, crafting a series of stories along the way, resulting in a white paper that provides an overview of the space and possibly where things are going.
During my conversations with Tony Tam (@fehguy) of Wordnik, creator of Swagger, Jakub Nesetril (@jakubnesetril) and Z (@zdne) of Apiary, creators of API Blueprint, and Uri Sarid (@usarid) of Mulesoft, creators of RAML, I asked a simple question:
What is the vision behind your API definition format?
Resulting in a little insight behind each approach:
- Swagger - The vision behind Swagger was not to make a company or to get people to use our service, it was strictly to solve a workflow problem. Initially the goal was centered around documentation and client tooling, but quickly realized it was much bigger, and became about managing the overall lifecycle of APIs.
- API Blueprint - API Blueprint is all about simplicity, and allowing people to have a structured conversation around an API, with the people who are actually going to be using it. Apiary is the conduit for this conversation, allowing developers to easily create a mock interface from the blueprint, share with consumers, and iterate as necessary.
- RAML - The motivation behind RAML was about seeking one source of truth, and a basic representation of an API. We used Swagger and API Blueprint, but neither fully met our vision. RAML was born, and is in alignment with Mulesoft's design first approach, and gave them the ability to design an API in a format that allowed them to sit down with stakeholders in a webinar and get instant feedback—bringing the API to forefront, not the implementation.
These are my summarizations of what Tony, Jakub, Z and Uri said in response to my question, not direct quotes. I think they get at the essence of why each company has invested so much in defining an API definition that delivers on their separate visions, and meets their goals
I also think there is a lot of overlap in these visions, as well as being in sync with where the overall demand in the API space is going. I don't endorse one solution over the other—I think each API designer will choose, and the fact there are multiple approaches is a good thing.
API definitions play a central role in my API design process, but in my personal approach, theAPI server and client code is regularly thrown away, where my API designs remain constant—something I work to iterate on, much like my writing.
Even with my personal passion for API definitions, I don't think they will be for everyone. I think API designers who find they deliver value in their work will use, while many successful API designers will have no use for them, and be just fine without them.
For some in 2014 API design will be about sharing, collaborating and communicating, in which API definitions will play a central role. For others the API implementation will be where the sharing, collaborating, communicating and ultimately the rubber meets the road.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- Where Do We Start With APIs At The University of Oklahoma?
- What I Would Look For When Hiring a Modern API Developer?
- The U.S. International Trade Commission Includes APIs In Latest Report
- Thank You @3Scale For Investing In The Community With @APIStrat
- Introducing API.Report, A Community API News Site
- Extract Knowledge From Audio And Video Using The Clarify API
- My API 101 Workshop At @APIStrat In Chicago Next Week
- Some Advice For The Enterprise When Beginning Your API Journey
- Machine Readable API Definition Format Swagger Matures to 2.0
- How Do We Continue Moving Green Button Data And APIs Forward?
- Beyond Public APIs In Government: Internal Access to Resources
- Can You Show Me The ROI On All Of This API Stuff Before We Commit
- In The Future APIs Will Be Default For All Cities
- No Public APIs Are Not Going Away Just Cause A Few BigCos Fumble At It
- Internal API Search Engine For Everyone At Your Company (Not Just Developers)
- If You Need Assistance With Your Healthcare API Strategy I Have The Person
- Explaining APIs To Senior Leadership: Access To Company Resources Without The IT Hassle
- A Conversation With @ijroth, @dorkitude, @antonyfalco, and @medjawii In The Next Generation API Stack Panel @APIStrat
- API Evangelist Thoughts On The Right To An API Key And Algorithmic Organizing
- Explaining APIs To Your Senior Leadership
- An API Evangelism Strategy To Map The Global Family Tree
- Thank You For Your API Evangelist Blog(s)
- Video From The Hypermedia Panel At API-Craft In Detroit Last Month
- Please Open Source Your API Before Shutting It Down
- Explaining My Work Around APIs In Higher Education To Institutions