As part of writing the book “Build for Developers - application developers as customers in API Economy” I do some research on related issues. During fall 2018 I did a survey on developer portals. It was targeted to Open Banking platform API consumers. Part of the survey contained questions about API on-boarding as well.

Learning how things are done with your API

Survey participants were asked how they would prefer to learn how API works and how to get started. Combination of documentation and working code examples was the most popular option. Simply providing working code examples would be the second best option. Using pseudo code might seem tempting “because it shows the logic and everyone can apply it to their preferred programming language”. No, it does not seem very attractive option for the API consumers.

Respondents were given claims which they needed to give value on Likert Scale (1-5). If API keys are required to consume your API, application developers expect to get them almost instantly and easily.

If you expect developers to request API keys with email and possibly wait days or weeks, you must have some sort of a (commercial) deadwish.

On top of the API keys getting started is valued high. You need to provide fast first positive experience with your API. Profound documentation with all the details clearly stated is expected but great documentation contains also getting started section.

What is API documentation?

Documentation and the importance of it was touched in previous chapters. Since poor documentation is the most common reason to ditch your API and go for the alternatives, it deserves to be discussed thoroughly.

Even though the title gives the impression that it’s a question of selecting which direction to take or confrontation between the two, it does not have to be that way. It’s not a question of either or. Getting started and good API documentation can and infact should coexist and support each other.

We’ve all read tons of API documentation. Sometimes the answers are easy to find but not always. From my experience great API documentation is not that common. Too often API documentation is a list of features with minimal descriptions, it’s not in sync with the implementation or just plain hard to access.

There’s reasons why documentation and manuals are not used. According to research people prefer “to solve their problem by asking a colleague or experimenting on their own”. instead of reading documentation. Reasons to ditch online documentation (and as a peer) are related to difficulties in navigating documentation, particularly difficulties in finding useful search terms, and disappointment in the level of explanation found. Thus you should make sure your documentation tackles at least the mentioned usability problems.

Asking peers for advice is also the reason why for example Stack Overflow (SO) is so popular. This brings us to an interesting opportunity. If the use of Stack Overflow is taken to the extreme, your API documentation could be based on the questions and answers in there. SO provides nice search function and quality of the answers is handled by the community. You can see the reputation of the people who provide answers. Thus you can easily evaluate how much you will trust the answer and is it worth anything. If your documentation sucks, it’s more likely that API consumers will look for help from SO. They might do it anyway especially if they have a problem with your API.

Thus it might raise the question, why do we put any efforts in maintaining poor documentation if it is hardly ever used? In addition to that you should seek answer to the question: what is the role of our detailed documentation vs community driven QA platforms? What value can be provide with the documentation that can not be provided by the community?

Modern APIs are expected to be taken into use as self-service. API consumers expect to find all needed information to work with your API without sending emails to you. Your duty as API provider is to offer excellent support from first encounter to replacing your API with another one. In this customer lifecycle API documentation and quick start guides have a slightly different but equally important role.

What is the difference?

What’s the difference with profound API documentation and quick start guide? Quick start guide is in essence a shortened version of a documentation, a useful reference, meant to make prospect API consumer familiar with the product as soon as possible. Often quick start guide contains less details and contains more complete code examples how to do specific fundamental operation.

API consumer needs to get first positive experience with your API fast, otherwise they are tempted to look for alternatives. This is where getting started type of content becomes your saviour. It gives the API consumer a glimpse of how things work without drilling into all the details and opportunities with the API.

What is quick start guide?

You might think that getting started is yet anothor separate document. That might be the case sometimes, but it does have other kind of forms too. There’s no single format or use case where quick start packages and guides fit. Let’s have a look at some use cases and examples. The purposes of why quick start guides are created vary too.

Console-alike instant playground

It makes sense to to offer quick start with the core functions and features with your API. Those features are used by majority of the API consumers and offering easy and fast instructions to jump in to your API is good customer service. Great examples of this are well-known Stripe and Pusher. Both offer getting started content in the (website) frontpage by providing instant try and learn console-alike playground. API consumer does not need to go anywhere else or download anything. They can just “click and execute“ to see how things work. Of course the approach has limitations since normally the examples are simplified, sometimes even to the extreme.

Reference apps

Another option is to provide sample apps, which extend the live console approach towards full applications. To see how API is used in simple app, probably enables faster knowledge transfer from API provider to API consumer than any detailed documentation could do. It’s not uncommon to provide client and server reference apps as open source. Twilio offers working client and server skeleton apps as quickstart guide in several programming languages. Each quickstart package contain short descriptions of steps to take before jumping to the code level examples. Code licensed under MIT and related readme is provided via Github.

Executable code in API documentation

Some API providers have more or less traditional API documentation, but it contains executable code examples or snippets as they are often labelled. With the snippets, you can’t really build a complete working app, but you can see how some API endpoint is used. Now the barrier has been crossed to documentation already.

If possible replace placeholder keys in code examples to real keys after login. This makes it faster to reuse the code examples in the testing phase. While building the real app, this feature does not matter. It is for the first few exepriements and make the testing more fluent.

After getting started…

Your tasks as API provider is to make consumers journey with your API as easy as possible, that includes fast successull usage of it (quick start guides). If you manage to enable easy first success with your API in minutes, it is more likely that developer will go deeper. In business language you have now prospect, not just a lead.

Now that the API consumer has been hooked with easy to try quick start guides and consoles, it’s time to go deeper. This the moment when profound and uptodate API documentation becomes handy. The API consumer already knows how to use authentication and use core value adding features of your API. The commonly used features sometimes is enough for the developer and there’s no need to look at your documentation.

Great API documentation:

Commonly pushed (by vendors and consultants) approach to create documentation is automatic generation. That hardly ever results to excellent documentation. I’ve tried different tools build on top of the most common API description specification OpenAPI during the spring 2019. As part of my job Developer eXeprience lead in the Platform of Trust, I had to define the API documentation process, format and resulted developer friendly documentation.

Excellent API documentation is not purely generated

From the experience I can claim that you can automate some part of the API documentation with tools, but excellent API documentation always requires some manual work. My approach to the API documentation was to start from the result. I crafted a sample of the result I wish to see in the API docs portal. I even tested the fully manually created result with some 3rd party developers before going any further. After that process was defined and implemented between the wanted result and internal development team devops process. We ended up putting all the docs in separate domain docs.oftrust.net and use open source Slate. The given code examples are now manually crafted from scratch, but we are exploring the code generation from RAML files. Getting the code generation to the level which is satisfactory is what still concerns us. We have pretty high standards.

Yes, we have automation, but the final touch is my responsibility. Machine readable API desctiptions are pulled from the code in continuous integration process and converted to Slate content automatically. After that some separately defined content files are pulled to Slate as well. Combination of automation and craftmanship is what creates our API documentation. API documentation is never released without human intervention.

This is the case for example with Stripe. Their documentation and product in general is considered as prime example among the API consumers.

Stripe documentation is combination of automation and manual work.

Great documentation looks and feels professional and is easy to read. If API documentation is found, it should offer detailed information about all aspects relevant for the consumer. Considering first encounter with your API, the consumer is not interested about the details and fine-grained ability to filter this or that. They want to get hands dirty as fast as possible. They want to see it in action. Thus providing quick start guides for the API consumer is fundamentally important for any API.

Stripe’s 3 column documentation is something that is used a lot and it seems to be quite popular among API consumers too. You can create similar 3 column documentation with Postman (under their brand) and open source Slate. Another popular format is OpenAPI spec model. The latter is popular due to variety of tools created to work with OpenAPI spec: server code, SDKs as well as documentation can be generated from OpenAPI spec file.

How to build awesome and loved documentation?

  1. Quite a many experienced API developers prefer to start from the end eg from documentation.
  2. Next to it is mockup API which is tested with sample code to see how it feels in everyday usage.
  3. The sample codes can be used in the API documentation after everyone involved is satisfied.

Quite a many experienced API developers prefer to start from the end eg from documentation.

This is not only about documentation. The described process involves the designing of your API in the same process. You design and mock your API before implementing it. You see the documentation before you implement it. In other words you know exactly what is the result from API consumers point of view before you implement the logic. No waste, no bullshit - just tested, well documented and efficient API.

Some more to read from 100 Days DX