Posted on 01-22-2014
I’m spending more time diving into the evolving world of API design over the next couple of weeks. There is a rapidly emerging community of companies, tooling and approaches to designing and developing APIs, that is centered around API definition languages.
Languages for defining web services have been around for a while, with Web Application Description Language (WADL), which was born out of the SOAP WSDL era, representing very technical approach to describing this new world of web APIs. While WADL is still in use, it hasn’t seen the adoption many envisioned.
It wasn’t until recently that we’ve seen new approaches emerge, and get traction, with JSON based API definitions like Swagger from Wordnik, and I/O Docs from Mashery. The primary motivation behind defining your API using Swagger or I/O Docs has historicaly been to deploy interactive documentation for developers, with discovery, client-side code generation, server-side code generation and other tooling as secondary motivator, if at all.
In the last year we’ve also seen even newer approaches to designing and defining APIs emerge, with the introduction of markdown based API definitions like API Blueprint from Apiary, and RAML from Mulesoft. This new markdown approach is providing languages for describing and defining APIs that holds the promise of even being accessible to non-developers.
I have time scheduled to talk with each of the providers listed above in the coming weeks, but after a talk with the API Blueprint team from Apiary, I’m reminded of how the motivations for API definitions is continuing its rapid expansion. When you are motivated to use API definitions for just generating API documentation, you miss so much opportunity for communicating, collaborating and iterating during the planning and design of your API.
API Blueprint was born out of Apiary, so it is rooted in the desire to design and mockup APIs, all while collaborating with other key players and the actual consumers of the API. If you wait to generate an API definition when you reach the point where you are ready for documentation, you are throwing away valuable design time, and burning costly development hours. Apiary needed a way to articulate, share and communicate around the design of an API from start to finish, pushing the motivation for developers to generate an API definition, from producing interactive docs, to devliering on the entire API planning, design, development, deployment and management lifecycle.
We need these new languages to describe and communicate around APIs. Without them we can’t mockup, iterate and collaborate to find the best possible API design. Without these new languages we can’t quantify APIs to key business, marketing, and sales players, as well as the lawyers, providing a contract for not just machine to machine interaction, but B2B and B2C. Without these new languages we can’t generate standardized tooling and API deployments based upon the best API patterns available today.
I think that the fact that there are now 4 major API design approaches, represents not just an evolution in the motivation for developers to use common definitions for APIs, but also a shift that will make API design accessible to everyone, motivating even non-developers to communicate and interact with APIs, in a simple, but powerful way that can align IT and development, with overall business goals.
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