APIs are like opinions: everybody has one... and most of them are bad. Luckily, the worst of these APIs are not for public consumption, just intended for a company's own engineers or partners. But why should they suffer? While there is plenty within API design that can affect quality, the most common reason for a bad experience is poor documentation.
Developers have been raising the bar on what is expected of docs. Among the almost standard fare now is interactive documentation. In this post, we'll show what it is, how you can get it for your own APIs, and how you can make your developers really happy.
What is Interactive Documentation?
Typical documentation explains an API's endpoints or methods, what data is expected with a request, and what is returned in the response. This is important information and should be available from any API.
Interactive documentation takes it a step further. Developers can see examples, but also fill in their own inputs. With a click of a button (that's the interactive part), developers see results on an actual API call to the service.
Everyone wants complete, accurate documentation. When your understanding can be augmented by seeing it in action, you're more likely to grasp what can be accomplished. The best way to add interactive features to your documentation is to first describe your API.
How Do You "Describe" Your APIs?
In the days before RESTful APIs, SOAP web services were documented with WSDL files. Standing for Web Service Definition Language, the XML format covered methods that an API can invoke and the type of data it receives. While SOAP is still used, most APIs now are based on REST (REpresentational State Transfer).
There are a handful of ways to "describe" REST APIs:
- API Blueprint is focused on collaborative API design. If you describe your API before you build it, you might make different decisions. This is especially true if you take the additional step of stubbing out endpoints that provide a mock version of the described API. You may determine that the developers who will build against your API can't perform the the desired operations. Much like building a house, if you discover issues in the blueprint stage, you save yourself a lot of effort building something that doesn't work.
- RAML (RESTful API Modeling Language) separates itself by including reusable snippets within its format. For example, you might have a user object that is returned by many different endpoints. Rather than describe that object over and over, RAML provides an easy way to describe it once and insert that description everywhere you need it.
- Swagger is the oldest and most popular of these three API description formats. In 2016 it became part of the Open API Initiative, an open governance structure under the Linux Foundation. Using a YAML description, Swagger tools can build SDKs, documentation, and more.
Each description or definition format has a bunch of tools around it, some of which are included in the section below.
Interactive Framework Options Abound
There isn't a compelling reason to create your own interactive documentation. You can choose from many projects that read in one or more description formats to make your documentation interactive. Unless you have incredibly customized needs for your interactive documentation, it makes sense to use something off-the-shelf.
DreamFactory, a mobile app backend, comes bundled with a Swagger-based interactive documentation framework. By connecting your database and creating a description, you get an API and documentation that can interact with it. You can try a developer trial account or deploy the DreamFactory blueprint on any CenturyLink Cloud virtual machine.
Similarly, you can use the Swagger-based tool directly. Called ReDoc, it's the next version of what was previously called SwaggerUI.
If you've chosen a description other than Swagger, you might look elsewhere:
- For RAML, look to the API Console project on GitHub. If the API Console is your jam, you can also convert Swagger to RAML.
- Apiary, the company that created API Blueprint, has interactive documentation as part of its product. Apiary also supports Swagger descriptions.
- Though not updated recently, you might also check out iodocs, which speaks multiple descriptions.
While the tools are often related to the descriptions, they don't have to be. You can find tools to convert between description formats. Or use an online tool, like API Transformer, which supports many different input and output formats.