Posted on 03-21-2013
It is becoming more common for API providers to deliver documentation using what's known as interactive API documentation, instead of the usual static API documentation. Understanding how to use an API can be tough sometimes, and rather than just reading about it how it works, interactive API documentation allows you make real calls against an API, while learning about the interface.
While there are several approaches to delivering interactive API documentation, my personal favorite is using Swagger. Swagger comes built in with 3Scale, which is the API management platform I use for the API Evangelist API, but Swagger is available for anyone to use as an open source project.
Interactive API documentation using Swagger starts with a Swagger definition, which is a JSON representation of an API endpoint. In this case, the endpoint is for accessing my blog posts:
This JSON describes everything about my very basic endpoint, which allows users to query almost 3 years of API Evangelist blog posts. Using this definition, Swagger generates the following API documentation automatically:
As someone learning about the API Evangelist Analysis API, this describes the endpoint, which fields are required to make an API call, but it doesn’t just describe this with text, it provides an interactive interface in which I can enter my API keys, provide a query value and actually make a request against the API:
So I don’t just learn about the API endpoint. I learn about what keys are needed and fields are present that allow me to request different information of the API endpoint. It allows me to actually see the request to the API, the resulting body of my API request.
This type of hands on learning is essential to onboarding new users with your API. I can read your API documentation and not see the value, but when I am walked through how to build a request, and actually see the value returned in real-time, it changes the game. As a developer I’m more likely to understand and integrate with an API when I am given interactive API documentation over static pages.
The benefits of describing your API using Swagger don’t stop with just providing interactive API documentation. Swagger can also help deliver code samples in multiple programming languages for developers to put to use, generate server side code for new APIs and provide potential benefits for API discovery.
It is well known that API documentation is the number one pain point for developers. Make sure your API documentation is hands-on, and interactive, so developers will understand the value your API delivers immediately, and go from learning, to integration, in as short of period as possible.
Disclosure: 3Scale is an API Evangelist partner
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