I am Kin Lane, the API Evangelist...

This is my online domain where I work to understand the world of the Application Programming Interfaces, also known as APIs. This new way of sharing data using the web is touching almost every aspect of our increasingly digital lives, providing access to the bits and bytes that make our personal and professional worlds go round.

This is my research specifically into how API providers are documenting their APIs. I am trying to identify the common patterns and approaches, and where the opportunity lies when it comes to providing much needed documentation around sometimes very complex and abstract APIs.

API Evangelist is a network of data driven projects and APIs which I curate and manage as part of this ongoing research, hoping to provide easy access to the moving parts of my work. Everything you see here runs on Github, making everything forkable, and reusable for both humans and machines.

API Evangelist Partners

These are my partners who invest in API Evangelist each month, helping underwrite my research, and making sure I'm able to keep monitoring the API space as I do.

DreamFactory Software develops and markets a technology that enables developers to connect modern mobile applications to enterprise back-end infrastructure in the cloud.

Latest From Blog on API Documentation: Getting Beyond OpenAPI Being About API Documentation

21 Sep 2017

Darrel Miller has a thought provoking post on OpenAPI not being what he thought, shining a light on a very important dimension of what OpenAPI does, and doesn’t do in the API space. In my experience, OpenAPI is rarely what people think, and I want to revisit once slice of Darrel’s story, in regards to folks generally thinking OpenAPI (Swagger) as being all about API documentation. In 2017, the majority of folks I talk to think OpenAPI is about documenting your APIs–something that always makes me sad, but I get it, and is something I regularly work to combat this notion.

First, and foremost, OpenAPI is a bridge to understanding and being able to communicate around using HTTP as a transport, and our greatest hope for helping developers learn their HTTPs and 123s. I meet developers on a regular basis who are building web APIs, yet do not have a firm grasp on what HTTP is. Hell, I’ve had a career dedicated to web APIs for the last seven years, and I’m still developing my grasp on what it is, learning new things from folks like Erik Wilde (@dret), Darrel Miller (@darrel_miller), and Mike Amundsen (@mamund) on a regular basis. In the API game, you should always be learning, and the web is the center of your existence at the moment as a software engineer, and should be the focus of what you are learning about to push forward your knowledge.

Darrel has a great line in his post where he has “a higher chance of convincing developers to stop drinking Mountain Dew than to pry a documentation generator from the hands of a dev with a deadline.” Meaning, most developers don’t have the time or interest to learn about what OpenAPIs, or can do for them in their busy world, they just want the help delivering documentation–a very visual representation of the work they’ve done, and is something they can demonstrate to their boss, partners, and customers. Most developers aren’t spending the time trying to know and understand everything API, thinking deeply on the subject like Darrel and I are doing. Most don’t even have time to read our blog posts. A sad fact of doing business in the tech space, but is something us in charge of API standards and tooling, or even selling API services should be aware of.

You see an essence of this with API code generators, and API testing from OpenAPI. Although in much lesser quantities than API documentation enjoys. Developers just want the assist, they really don’t care whether it is the right way of doing things, or the wrong way, and how it fits into the bigger picture. API developers just want to get their work done, and move on. It is up to us analysts, standards shepherds, and API service providers to help educate, illuminate, and incentivize developers to get over their limiting views on what OpenAPI is and/or develop the next killer tooling that helps make their lives insanely easier like Swagger UI did for API documentation. We need to learn from the impact this tooling has made, and make sure the other lifecycle solutions we are delivering speak in similar tones.

If you are reading this piece, and are still in the camp of folks who still see OpenAPI as Swagger UI, don’t feel bad, it is a common misconception, and one that was exacerbated by the move from Swagger to OpenAPI. My recommendation is that you begin to look at OpenAPI independent of any tooling it enables. Think of it as a checklist for your HTTP learning, sharing, and communication across your API development team. It shouldn’t be just about delivering documentation, code, tests, or anything else. OpenAPI is about making sure you have the HTTP details of your API delivered in a consistent way, across not just a single APIs, but all the APIs you are delivering. OpenAPI is the bridge to where you are now with your API operations, to where you should be when it comes to the definition, design, deployment, management, and delivering sustainable contracts around the digital assets you are serving up internally, with partners, and 3rd party developers. It may see like extra work to think about it this way, but it is something that will save you time and money down the road.

API Documentation News

These are the news items I've curated in my monitoring of the API space that have some relevance to the API definition conversation and I wanted to include in my research. I'm using all of these links to better understand how the space is testing their APIs, going beyond just monitoring and understand the details of each request and response.

If you think there is a link I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.

API Documentation Organizations

These are the organizations I come across in my research who are doing interesting things in the API space. They could be companies, institutions, government agencies, or any other type of organizational entity. My goal is to aggregate so I can stay in tune with what they are up to and how it impacts the API space.

SDK Bridge is a company that specializes in explaining technology through documentation and software development kits. It provides a variety of API-related services including: API Documentation Sample code and tutorials Highly technical copywriting Training sessions on how to use software platforms Technology classes for youth These services can be a critical piece of delivering your API. SDK Bridge says that it is a bridge between people and technology. So very true. SDK Bridge provides a set of services that any business looking to deliver an API should evaluate. Even though you many be able to generate your own marketing materials, SDK and other supporting API documents, you may find more value bring in an outside perspective to make sure you explain how your API solves problems, adds value, and can be successfully integrated to customers systems.

ReadMe is a developer hub for your startup or code. It's a completely customizable and collaborative place for documentation, support, key generation and more. Don't waste your precious time reimplementing a dev.yourstartup.com. If you have an API, code library, or affiliate program, documentation is hard. Users can't use your product without understanding it, and most documentation on the Internet is lacking. The goal of ReadMe is to make consuming APIs completely painless.

Confluence is a wiki used by more than half of Fortune 100 companies to connect people with the content and co-workers they need to get their jobs done, faster. Connect your entire business in one place online to collaborate and capture knowledge – create, share, and discuss your documents, ideas, minutes, and projects.

Our mission is to help REST API providers easily create SDKs in different programming languages with easy-to-follow documentation and code samples while software developers can effortlessly consume the REST API by following the SDK installation instruction and using the code samples within minutes.

Dexy helps your code to speak for itself. Show off your code with beautiful syntax highlighting. Write examples and Dexy will run them, inserting the output into any document you wish. Everything is based on live code, so updating is easy, syntax errors blow up on you, not your users, and typos are a thing of the past. With Dexy's smart caching, your code is only executed when it needs updating, saving you time while keeping your documents robust.

Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. We support webhooks so your docs get built when you commit code. There's also support for versioning so you can build docs from tags and branches of your code in your repository.

Apiary.io is a hosted suite of tools that help companies build web APIs quickly, test and monitor them easily and document them effortlessly. It provides API owners with necessary infrastructure and helps them build relationship with their users. Core of the self-service solution is API Blueprint, an efficient format for describing an API, aspiring to define new gold standard for REST API development. The product uses this Blueprint to streamline adoption of new services and simplify integration to other systems.

Gelato.io is a tool for creating really great API Documentation and Developer Portals. You can describe your API, import and sync with Swagger or API Blueprint, write awesome guides (or get them written for you), have your developers register and get updates when things change, get an automatic API Explorer - everything a good Documentation Site needs and more!

If you think there is an organization I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.

API Documentation Tooling

As I study each API, and API related service, I'm always looking for open source tooling that has been developed around each area of the API life cycle. This is an aggregate of tooling I've come across and aggregated as part of my API testing research.

An API Blueprint renderer that supports multiple themes and outputs static HTML that can be served by any web host. API Blueprint is a Markdown-based document format that lets you write API descriptions and documentation in a simple and straightforward way.

API Changelog monitors the docs of APIs you depend on and sends you notifications when they change. API Changelog is brought to you by Runscope. Solve API errors fast. Debug, test and share your API calls.

API Console is a graphical user interface for a RAML-defined API that visually exposes the API’s structure and important patterns and serves as interactive API documentation. It is provided under the open-source CPAL license.

apidoc and swagger are two nice projects which are focusing on documentation of APIs. This project is a middle tier which tries to bring them together in a sense that it uses apidoc to convert inline documentation to json schema and later convert it to swagger json schmea.

Carte is a simple Jekyll based documentation website for APIs. It is designed as a boilerplate to build your own documentation and is heavily inspired from Swagger and I/O docs. Fork it, add specifications for your APIs calls and customize the theme. Go ahead, see if we care.

Docbox is an open source version of Mapbox's REST API documentation system. It takes structured Markdown files and generates a friendly two-column layout with navigation, permalinks, and examples. The documentation source files that Docbox uses are friendly for documentation authors and free of presentational code: it's Markdown.

If there is a tool that you think should be listed here, let me know by submitting a Github issue or Tweeting a link at me. I'm always looking for new types of tools, and get better at organizing them here and making sense.

API Documentation Building Blocks

As I study the API space, and profile the companies, services, and tooling I come across I'm always looking for the common building blocks in use across API operations. These are derived the features, and valuable elements of API operations, and the companies who are servicing this particular area of the API space.

Elements

Documentation - Simple, easy to understand, documentation of what an API does, that is kept up to date with API roadmap.

List of Endpoints - A simple listing of all endpoints provides a quick introduction of what is available with an API.

These building blocks are constantly being added to and reorganized. If there is something you think should be here feel free to let me know. Remember that this represents my living research, and will evolve, expand and actually seed new research areas as I find the time to pay attention to API testing.

About This Research

As I keep an eye on the space I curate news, bookmark organizations, watch interesting tools, and work to understand what deployment solutions are being applied by leading API providers. I take everything I find and publish here as part of my research.

I then take this research, and what I've learned and publish stories on the blog, and more long form content like my industry guides, and white papers for customers. This is one way that I generate revenue to keep it all going.

If you'd like to see me focus more on API documentation I could use more partners investing in this area, helping me find the time to study more about what is going on. Feel free to contact me directly if you want to talk more about API documentation.