Air France-KLM API Developer Portal Developer Blog

Let's talk about an awesome API developer portal

In the afternoon of the 6th July, Robert Zazueta (Rob Z) of TIBCO Mashery visited Air France - KLM to talk about best practices around developer portals and API documentation. Together with Aleks Yanchuck of the API Readiness team within Air France - KLM he addressed the topic of how to build an excellent developer portal. Many different people from the company attended this interesting event, and we'll probably host more of these across the different locations of Air France - KLM.
In this post, we would like to offer a short summary of the key points and highlights the speakers delivered. 
Rob Z started with the emphasis on the onboarding experience and the importance of the developer support. Rob has been emphasizing that a good API starts with a clearly articulated unique value proposition that the API offers. Along with the functionality, it is extremely important to provide tutorials and sample code so that the developers can get started quickly.

If you haven't heard the term "value proposition" before, we recommend reading this LinkedIn article explaining what's in the value proposition that an API may be lacking.

Documentation on the developer portal is the first point that developers will consult or encounter. The most important property of good documentation is discoverability and searchability, either via a search engine or via Ctrl+F. Therefore all documentation needs to be textual. "Stick to HTML  – and No PDFs!" – according to Rob.

The documentation itself is not enough, however. Eventually, people will come up with "edge" use cases that are not covered. It is important explain the onboarding and support procedure up front: how to sign up, how to get a key, how to contact a human for support. Next to explaining the "how" bit, giving a clear timeline for response is also a pre. According to Rob, these timelines to get support need to be very closely watched and followed – to the extent that these need to be treated as an SLA towards an external party.

The support does not need to be confined to the developer portal only., for instance, is a great source and for many developers a go-to place to ask questions and get answers. An empty forum, though, will put many people away. To overcome this, internal developers can create the initial critical mass of content, and then the community will take this over and will keep the forum self-sustained.
The documentation and code samples need to be in sync with the current state of API, and free of the future promises or discussions. (A side note from the API Readiness Team: blogs is the place where you can discuss future changes and releases. However, we will not recommend blogging about the upcoming features if a product team cannot commit to delivering exactly what and when they promise.) The code samples need to work. In Rob's experience, most of the support cases are attributed to the code samples not working as the narrative around these code samples suggests.

Check out the developer portals covered in Rob's presentation
1. Getty:
2. Food Essentials:
3. Rotten Tomatoes:
4. Athena Health:
5. Vertical Response:
6. Under Armour:
7. Twilio:

A bit of counter-intuitive advice from Rob: do not invest in an SDK unless you see the value in it. The rationale: the SDK needs to be available in all major languages. And, the SDK (or, rather, SDKs) have to work and withstand use and "abuse" by enthusiastic developers.

Aleks Yanchuk continued building on the message delivered by Rob to illustrate that many product teams are closer to producing professional API documentation for the developer portal than they think. Of course, reaching the goal is not easy, but Aleks wanted to emphasize that it is perfectly doable.

The key to writing less is a concept of information visibility: focusing on what an API consumer can see from his perspective and limiting the description strictly to this scope. Additionally, Aleks advocates critically looking at each sentence and asking yourself, "what do I want a developer to do with it". Aleks also covered the structure of the developer guide and what each section should contain.
To summarize: in an API world, consumer-facing documentation is a critical success factor for extending your reach to more digital channels, even ones beyond direct control of the company. The effort to produce a "polished to the bone" content of the API documentation is a "first-class" citizen for the product team. 

It will not be easy to get there, but with our new developer portal we have taken some steps in the right direction. Nobody's perfect, so we would love to receive your feedback on the portal and the quality of the documentation that is published on it. Over time, our portal will improve as we add new features implement improvements, and build a lively community around our APIs. We're inviting everyone to become part of it!