Air France-KLM API Developer Portal Developer Blog

RSS Feed

A new API available in Open Data !

Did you ever wonder if you would be able to recharge your tablet whilst being on the internet on your plane ? And what are you going to have for dinner by the way ? What kind of entertainment will be available?  

Everything about all those fancy amenities provided on one’s flight is just a few calls away!

 

Inspire API / Amenities is right now available in the Open Data plan, go ahead and play with it!

 

 The Air France-KLM Developer Portal Team

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. Stackoverflow.com, 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: http://developers.gettyimages.com/nl/
2. Food Essentials: http://developer.foodessentials.com/
3. Rotten Tomatoes: https://developer.fandango.com/Rotten_Tomatoes
4. Athena Health: https://www.athenahealth.com/developer-portal
5. Vertical Response: http://developers.verticalresponse.com/
6. Under Armour: https://developer.underarmour.com/
7. Twilio: https://www.twilio.com/

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!

Welcome to our new developer portal!

We're very pleased to release the complete redesign of our API developer portal. APIs have been at the center of Digital Strategy of Air France - KLM for a couple of years now. Our architecture has made the transition to an API first architecture, enabling us to provide our customers with a seamless and consistent experience across our different digital touchpoints. While at first, our APIs were primarily aimed at supporting our internal front-ends, we have started to open up some of our APIs to the outside world, in order to allow us to be where our customers are, by giving external parties the opportunity to integrate parts of the customer journey of Air France - KLM passengers into their own applications.

A professional developer portal is a key enabler for this. Our previous portal, which was put in place quickly to facilitate hackathons, has been replaced by a professional solution that provides a clear overview of the different APIs we have opened up to external parties.

Navigation has been improved: the portal now naturally guides the visitor through the discovery of our APIs. The way we present our API documentation got a major overhaul as well. It is now more clear which endpoints belong to which API, and how they are related. It is also easier to navigate between products and more detailed documentation.

Products now have a dedicated page in which their functionality and value can be explained on a high level.

We will keep improving the portal, iteratively adding new functionality. We plan to add a Forum and FAQ soon, as well as a Showcase section.

Keep you posted!


[ Page 1 of 1 ]