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.
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.
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.
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.
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.
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: .
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.
Developer Portal: Strategy Series, Part 1 Through this series of posts we aim to provide you with strategies for raising the standards of both internal or external developer portals.
