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
- My Discussion Today With 6 Hypermedia Leaders At API-Craft in Detroit
- Getting To Know Jørn Wildt For The API Craft 2014 Detroit Hypermedia Panel
- Hypermedia Feels Like We Are Still Learning To Communicate With APIs
- Getting To Know Markus Lanthaler For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Kevin Swiber For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Steve Klabnik For The API Craft 2014 Detroit Hypermedia Panel
- New Indix API KickStart Program Reduces Costs For Developers
- Getting To Know Mike Kelly For The API Craft 2014 Detroit Hypermedia Panel
- A Shared, Distributed Experience(Metrics) Layer For The API Driven Application Stack
- Showcasing Your API Integrations With Other Platforms
- Increasing The Focus On APIs In Higher Education Is Important
- Getting To Know Mike Amundsen For The API Craft 2014 Detroit Hypermedia Panel
- The New StrongLoop API Server Provides A Look At Future Of API Deployment
- Models For API Driven Startups Built Around Public Data
- 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 18F's, 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