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
- The New StrongLoop API Server Provides A Look At Future Of API Deployment
- Will You Add Me To API Evangelist And How To Spot The Cool Kids
- When I Remix APIs Using Swagger How Do I Deal With Authentication Across Multiple APIs
- It Takes A Team Of Evangelists To Raise An API
- Support For Only Two Creative Commons Licenses In The API Commons
- Machine Readable Terms of Service Didn't Read Applied To APIs Via APIs.json
- API Deployment For Non-Developers Using Zapier, Google Docs, and APISpark
- State of Hypermedia Today @ API Craft In Detroit
- Need A Formal API Standard For Your Government Agency? Fork 18Fs, And Make It Your Own!
- CORS Makes Your API Portable And Remix-able
- Chief Data Officer Needs To Make The Department Of Commerce Developer Portal The Center Of API Economy
- An API Definition As The Truth In The API Contract
- Look At Existing APIs In The Space Before Designing Your Own
- Libraries Hacked: UK Library API, Data And Technology Hacks
- Financial Data Aggregator Yodlee Looking For A Director of Developer Evangelism
- AutoDevBot Open Sources Their API Monitor
- Low Hanging Fruit For API Discovery In The Federal Government
- Looking At 77 Federal Government API Developer Portals And 190 APIs
- Applying APIs.json To API Discovery In The Federal Government
- The Power In API Discovery For APIs.json Will Be In The API URL Type
- Fixing The Machine Readability in API Commons
- Evolving How We Approach The API Lifecycle With APIMatic
- APIs Can Open Up Your Company To Outside Ideas
- APIs Are Often Just A Facade That Is Covering Up The Legacy View Of World
- A Mobile Developer Toolkit With The University Of Michigan APIs