This is the first post in a 6 part series about API strategies. If you’d like to get notified about the next posts, subscribe to our newsletter.



Developer portals are important for your API's adoption and support. They are also a trust signal: a well designed and actively maintained developer portal shows that an organization is investing in its APIs. It helps convince developers that they can rely on them.

This matters: many developers have in their career dealt with the fallout of a deprecated or suddenly discontinued API, especially more experienced developers will be cautious when introducing dependencies. API trust signals are therefore crucial when you run an API program that primarily targets developers outside of your business, but they can also play a role for internal APIs in large organizations where business unit politics can result in information asymmetries.

In this post I’ll zoom in on 7 trust signals that I think are important, all of them - except maybe for nr. 3, API quality - can be asserted through an API's developer portal.

1. Business model

In 2014, Linkedin changed their terms of service. Overnight the majority of CRM projects found themselves shut out of Linkedin's API program. Linkedin had decided to limit API access so that only Salesforce and Microsoft Dynamics would be able to use it to augment their CRM products. This was a disaster for several smaller CRM solutions that had made their integration with Linkedin a key strategic differentiator.



Because of stories like this, developers have become more careful about the APIs they invest their time in. It is extremely important to be upfront about the business model of your API. If your API is free, you need to explain why and how you will keep on supporting it. If you have a paying API you need to make it clear that your plans are sustainable, and that you won’t suddenly change the conditions for your customers and partners.

Keen IO’s Business Models (screenshot January 2017)



Twilio’s personalized support models



2. Partner policy

Related to point 1, it is important to have a clear partner policy. Successful APIs allow organizations to turn their services into a platform on top of which other businesses can innovate. In their book ”Platform Revolution” the authors describe why platforms need to absorb popular features originally developed by their partner ecosystem back into their core product. If they don’t do so, they risk being replaced by a more popular partner who could capture the market with a better default core product.

In the book, the authors, also describe that this needs to be done carefully, to make it clear that partners will be able to profit for at least some time, before the platform absorbs those features. If it is your ambition to build a large sustainable ecosystem around your business to make your product more robust and innovative, it is important to consider a platform strategy as part of your your partner policy.

A clear terms of use for an API prevents misunderstandings and abuse. But caution is needed, if the terms are too strict or avoid a clear commitment this might create suspicion and undermine trust.



3. API quality

The quality of your API will of course be one of the most important trust signals for developers once they start working on their integration. A badly designed API will not only reduce the developer experience, it will also raise doubts about your API team, their resources, and commitment. Joshua Tauberer wrote a blog post that lists out a number of qualities that can improve your API on his blog. Another great resource is 5 Features of a Good API Architecture, a talk Rob Allen gave at OSCON.

“A good API is secure” (Rob Allen) - Example of a security section (Keen IO docs)



Example of listing and describing error messages to speed up the developer’s job (Stripe)



Providing fully working Libraries - in several code languages - into the API Documentation improves implementation quality (Dropbox)



4. API uptime status

Another way to build trust is to provide a page on your portal where developers can check the current API status of the system they’re working with.

Bonus points if you include a sign up possibility to receive updates and a diary of past incidents. Twilio, Dropbox and Vimeo use Atlassian’s StatusPage product to do so.

Including a general API status overview helps assert the quality of an API product (Twilio)



API status system metrics (Vimeo)



5. Versioning policy

The long term stability of your API will depend on a proper versioning strategy. Having a versioning policy in place from the start will show that you are planning for the future and that there will be further investments in your API. Most web APIs nowadays use URL versioning, but there are arguments against this approach. To learn more about versioning options, read Troy Hunt’s blogpost on the subject, he also has a discussion about URL versioning in his comments, so don’t skip them.

Example of a docs page with buttons to switch API versions (CenturyLink)



6. Documentation

Even when developers see the importance of documentation and/or like writing docs, they often don’t get enough time to do so. The results are unmistakable, according to Stackoverflow’s 2016 survey, "poor documentation" was the 2nd most important challenge that 34,7% of developers faced at work just 0.2% after "unrealistic expectations”.

Documentation also functions as a quality signal that shows the level of investment you have made in the developer experience of your API. Do you have reference documentation for your API? Is it interactive? Do you use one of the REST API documentation standards? Did you create a thesaurus of the domain language, to explain terms that developers, new to your industry, might not be familiar with? Do you have tutorials and getting started documentation? A lot of API teams mistakenly believe that reference documentation is the only type of documentation an API needs. To learn more about the different documentation components check out Kathleen’s blogpost series about documentation patterns on developer portals or subscribe to our newsletter to get our white paper about developer portal components: .

Twilio’s documentation overview page, including Quickstarts, Guides, Tutorials, API reference and SDKs sections



7. Developer portal production quality

Last but not least, don’t underestimate the importance of your developer portal’s production quality. The design and completeness of your portal will give an impression about the trustworthiness of your API. Developers might not consciously think about this, but a good developer portal can be a signal that you are not cutting corners, and that you are committed to your API program. Regular updates to your portal, through blog posts, event postings, and documentation updates show that you are (still) investing in your APIs.

Keen IO’s community portal provides developers with several possibilities to communicate and meet



CenturyLink’s overview page for developers includes links to documentation sections and to their blog



Other posts in this series:

Introduction: 6 Models and Frameworks to Help You Build Better Developer Portals
Part 2: The 8 Stakeholders of Developer Portals
Part 3: 3 Maturity Models for APIs
Part 4: Inspire, Educate, & Authorise - Developer Portals and Jobs to be Done
Part 5: The Developer’s Journey - Developer Portals Need More Than an API Reference
Part 6: Public, Catalogue, Partner, & Utility APIs - 4 Developer Portal Archetypes



About the author

Kristof van Tomme

CEO, Co-founder

Kristof is a Drupal strategist and architect with a degree in bioengineering. He started his career as a technology manager. At Pronovix, the company he co-founded, he’s been focussing on Drupal since 4.7. Recently his interest in DITA and reusable, single source documentation have culminated in the WalkHub.net project, an open source project that aims to become the GitHub of website documentation.

He initiated and later became the co-organizer of an introductory Drupal course at the University of Szeged (Hungary). As a permanent member of the Drupal Association, he was at some point the lead for the selection task force for European Drupalcons and of the inaugural Nomination Committee. Among others, he was the initiator and (co-)lead of Drupalcon Szeged (2008), DrupalCXO Brussels (2010), Drupal Developer Days Brussels (2011) and Drupal Government Days (2011). Currently he is involved in the organization of the Write the docs unconference in Berlin (2014 July).