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
- 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
- Which API Do I Need?
- The Expanding API Conference Landscape
- Ocotoparts Open Source Google Spreadsheet
- Andrew Nacin Of WordPress @APIStrat Chicago
- Push Button API Deployment With The Heroku Button
- WordPress Style API Modules For Government
- The Heroku HTTP API Design Guide
- What I Have Been Calling API Trends, Are Slowly Being Baked Into API Operations
- FDA Finding Their API Mojo With A New Drug Label API
- Adding PokitDok To Healthcare Research And The API Stack (Well They Did)
- Why I Am Continuing To Integrate Zapier In My Business Workflow
- Who Is Going To Build The Uber API Platform For The Sharing Economy?
- The API Focused Dev Shop
- Route SMS Messages To Google Spreadsheets Via Twilio API With TwilioSheet