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
- 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
- You Can Have An API Just By Choosing Products And Services That Have APIs
- Using Excel As An API Datasource And An API Client For The Masses
- Brewing Up Something Awesome With The Jive Software API
- Relationship Between APIs And Containers
- Real-time and Visualizations Will Be Key in Financial API Deployments
- Notification Focused Startups Within Leading API Ecosystems
- APIs That Do One Thing And Do It Well Like ZipLocate