The telecommunication sector was one of the earliest adopters of APIs and today it is one of its most important and largest markets. During our research we examined both telecommunication carriers and companies like Nexmo and Twilio, which are often referred to as API vendors. What we were suspecting from the number of publicly available developer portals among the two groups has been confirmed by other resources too: as a developer or a system integrator will most likely choose an API vendor when in need of an API, these vendors are more likely to invest highly into their public facing developer portals. More traditional telecommunication carrier companies on the other hand benefit greatly from internal and partner facing developer portals, as they can facilitate the development of new services and remove friction for their internal and partner developers. However, more and more carriers have started to commit to an external API program, and we really wanted to also include them in our sample.
That is why in this post we would like to present some great examples offered by a selection of telecommunication carriers from all around the world, such as Orange and Telenor from Europe, AT&T from the USA and Telstra from Australia and also by API vendors such as Proximus EnCo, Nexmo and Twilio.
We will evaluate along two main areas:
(1) the available information sources to onboard a developer (such as tutorials, conceptual and legal documentation, support, use cases, etc.),
(2) API docs quality criteria (interactivity, readability, usability, information on pricing).
You can read more about the background to these two concepts and why we chose them in our introductory post.Read more
We modelled the steps taken by a developer persona looking for an API implementation from start to finish, and we follow this downstream developer journey to find the industry's current most innovative and remarkable solutions in architecting and presenting information on a developer portal.
Discover and research
How can this portal help me solve my specific task?
Most companies have a site for API marketing and a separate site for the API's developer documentation. From what we've found, Nexmo’s marketing site contains information that we can often find on developer portals, such as an overview of the APIs, use cases, success stories and a blog. The general site, nexmo.com, gives an overview of the whole platform and also of the APIs but the documentation for each API and a try out section is also available from this site’s menu pointing to the developer portal. This shows that it actually targets both developers and decision makers. The devportal, developer.nexmo.com is an API catalog with developer documentation in the strict sense: overview, guide, tutorial and reference.
Developer portal landing pages often focus on the products themselves by providing a catalog. AT&T offers various products that they present on the landing page of their developer portal. The APIs are clearly indicated.
Proximus EnCo offers different entry points for different audiences: the EnCo Market links to their API (and other products) catalog, but code-oriented developers can register right away. For first-time visitors there is also a short video explaining what Proximus EnCo is about.
Nexmo has detailed, decision maker focused overview pages for each API. There are illustrative use cases to show the possibilities of the API and also partner showcases of real life integration successes. The relevant blog posts are also highlighted on these pages. We must mention that Nexmo seems to be doing an exceptional job at providing the right information and entry point for all of its possible audiences - the menu on the API overview pages offers four options: For your business, For your build, Features and Pricing.
Once users have found the API they are interested in they might want to get a clear iteration of what it is capable of, what it can be used for. There are different methods to provide this. Orange inserts several visuals into the overview of its APIs.
For its Form filling API Orange also provides a use case in form of a video.
Telstra has an interesting approach for providing an overview for its Event Detection API - the most important features are revealed in the form of a Q&A.
Can I trust this organization’s commitment to its APIs?
In our understanding, the evaluation phase is on one hand about making sure that the organization and its APIs are trustworthy, and on the other hand about getting an understanding of the workings of the API(s), often through setting up a test account.
As we have mentioned in our previous posts, proper information on versioning and release notes are prominent in inducing trust in your APIs. They often get prime real estate on a developer portal, like on AT&T’s or Orange’s site. Orange also has a Release log for each API (where relevant).
Where do I begin? Well-designed tutorials, quickstarts and how-tos are probably the best antidote against API friction in the getting started phase.
Twilio uses an interesting approach, probably with the aim to better guide its users: the quickstarts are step by step guides. They are broken up into smaller parts, and in the end of every section users can confirm that they have understood the previous part and ready to go on to the next one.
Twilio’s user friendly solution doesn’t end here. The quickstart contains several screenshots, which can be enlarged by clicking on them, and it also offers a video version of the whole process.
Making sure that users understand the terminology relevant to the industry of telecommunication and the world of APIs can help a lot in the getting started phase.
Nexmo offers a list of concepts of API terminology on its general documentation page, and it also highlights the relevant concepts on the specific API's page.
Orange Developer also begins its getting started documentation with a terminology list.
Filling the getting started documentation with visuals on the workings of the APIs or the authentication processes can help users easily understand the products without having to read lengthy texts.
Structuring the getting started documentation around SDKs might also be a good idea, especially for code-oriented developers.
Twilio offers SDKs with various options in their Quickstart section. Not only can you check the output for the code with a simple click, but its GitHub repository is also available the same way. There is also a copy button or a link can be assigned to various parts of the code.
Nexmo also offers SDKs for different languages. The style of this section suggests that Nexmo would like to gain the trust of developers even with its appearance: the tiles of the SDKs follow the icons and style used by GitHub. Most developers are familiar with this style so it is a user friendly solution for them - it makes scanning for relevant information much easier.
Implement and troubleshoot
Do I know everything to make this work?
Although reference documentation in itself is not enough for a portal, it is still one of the most important components. Similarly to banking and FinTech portals, the three-column reference docs structure is popular among telecommunication portals too.
Twilio enhanced their three-column references with great tools, such as Output, Copy, a Link to this Code , and access to their GitHub repository buttons. Nexmo also has three-column layout for reference docs with a language selector.
To make it easy for developers to work with the APIs various troubleshooting options are a must. Generally we can talk about three forms of troubleshooting here: self-service support, such as FAQs and knowledge bases, peer-to-peer help in the form of community sections and forums and professional assistance from the API provider, usually attainable via a contact form. The developer portals we have checked in the telecommunication industry provide great examples for all three.
For FAQs it seems to be a best practice to clearly tag them according to the specific API or the general problem area, like Orange or Nexmo do. AT&T and Orange uses a different approach: the focus is not on a separate FAQ section, but the documentation for each API contains the relevant FAQ. A useful extra with AT&T is that the dates when the answers were given or last updated is also indicated.
The research we consulted showed that developers often turn to third-party resources for peer-to-peer help. In a previous blog post we have argued that these platforms can have numerous advantages, for example developers most probably have an account so they are already aware of the culture required. One of the most popular choices is usually StackOverflow, so it’s not surprising that Orange and Nexmo both offer access to it on their support pages.
Every portal that we checked offers a contact form, but there are exemplary solutions. Does it seem enough to provide an email address users can write their problems to? The whole support process can be made much more effective if the relevant person/department gets your question, with the details they need to actually help you. On Orange’s support section users are asked to choose from five categories with several subcategories in each.
Twilio also has a very detailed contact form. It asks for a detailed description of the problem, and you can further elaborate with an attached file. Users should also indicate the urgency of the problem in the contact form, which again can make support more effective.
AT&T has a similar solution. It offers several routes for self-help: check the FAQ, turn to the forum or check Twitter. Direct support can be reached by submitting a ticket, for which users have to choose a topic and they can also indicate the priority of the problem.
Telstra also has various options on its support page: they refer one to a Forum, a Twitter account and an email address. What it highlights is a separate sales enquiry contact form and a phone line dedicated to billing enquiries, and for users who purchase an API plan it also offers a 24/7 support desk. Twilio also offers a separate Talk to sales option on its support page.
Will they care about my work? A developer portal can show appreciation towards its users by asking for their feedback (and taking it seriously). Nexmo asks if users found their documentation useful with a simple choice up or down and asks for optional suggestions on improvement. There is also a link to GitHub for users who prefer this way of communication.
Behind sign-in Nexmo uses an integrated external UX tool to collect feedback: users are asked to give a 1-5 rating and share their experience using a handy tool to select and show which part of the site they are giving their opinion on.
Kat King, developer educator at Twilio narrated in a presentation last May how they leveraged direct user feedback (from Twitter) towards a better UX. They went on to ask for both quantitative and qualitative feedback on their docs and have been working on improving them ever since based on the collected data. First users can rate the docs on a scale from one to five and if the rating is 4 or below they are asked to suggest improvements.
A well-maintained community section can be beneficial for both users and API providers. On one hand it again shows users that their efforts and opinions are appreciated, on the other API providers can easily get an insight into the interests and preferences of their users. The Events and Blog section of AT&T show that they pay great attention to community building. The first contains numerous events for developers while the second offers reading in various topics which can be filtered by category.
Twilio and Proximus EnCo also have a blog, while Nexmo nudges all the “resources for and by the community” in one place: its Community section contains videos from Youtube, upcoming events and a Slack channel.
Nexmo's devportal goes for recruitment too: it calls for one's job application right on top of the page. The “We’re hiring” sign links to the job advertisements, where apart from listing the present team members Nexmo makes a small, yet important gesture towards the community: it highlights the list of contributors on GitHub.
How hard will it be to keep this running?
Nexmo and Twilio set a great example by providing a separate API service status page. Both pages follow the same layout structure. It helps the user identify the relevant information faster. We can say that the two companies are offering a pattern that can be used as a best practice. The most recent updates are highlighted on top. There is a possibility to subscribe to updates, and past incidents can also be checked as you scroll. Another extra feature that provides information on the working of the APIs is the system metrics.
After signing in to the Nexmo platform we discovered one more little gesture that can help in building trust: apart from the usual confirmation mail I got an automated email from one of Nexmo’s support person, offering his assistance via email or phone (for which I also got a number).
A sandbox environment does not seem to be a common practice among telco developer portals, unlike in the case of banks and the FinTech sector.
The portals we checked do pay attention to interactivity, and to give an opportunity for users to try out the APIs. Nexmo for example provided credentials and a €2 free credit after sign up.
Twilio strives to enhance readability by breaking up the quickstart guides to smaller chunks. Nexmo uses a technique that we have also noted in FinTech portals part of this series: it offers a Table of Contents at the beginning of each part of the documentation.
The dynamically changing URL, which provides a direct link to each section of the documentation that we can see with Proximus EnCo, Nexmo, Twilio is a feature that can greatly enhance usability. Besides the URLs Twilio uses breadcrumbs to make it easy for users to navigate back and forth in the documentation.
Information on pricing is super important of course and there are great examples on how it can be provided clearly among the portals we have checked. Both Nexmo and Twilio offer a table describing the services provided by the different support plans, while Proximus EnCo has an additional downloadable spreadsheet with information on pricing in all the countries where its SMS API is available.
The developer journey stages and great API documentation practices
Visuals on the working of the APIs
|Evaluate||Information on versioning
Fast and easy registration process
|Implement and Troubleshoot||Reference docs
|Celebrate||News & Events
Beyond great documentation
We firmly believe that no matter how great an API is, without a good developer portal it can never achieve its full potential. Twilio, one of the biggest API vendors, has been cited as an example to follow among developer portals for a long time, and there are other portals too that are worth checking. We hope we could come up with a comprehensive sample of developer portals and best practices offered by them. However, we might have missed some portals, so feel free to recommend them in a comment below or even better, nominate them for the DevPortal Awards.
The portals we analyzed
For this part of our series we brought examples from the following developer portals:
Monika presents these research results at APIDays Amsterdam on 17 October 2018. See you there!APIDays Amsterdam
Posts in this series:
- Introductory post
- Analyzing the API Docs and DX Patterns in the Best Banking Developer Portals
- Analyzing the API Docs and DX Patterns in the Best FinTech Developer Portals
- Analyzing the API Docs and DX Patterns in the Best Media Developer Portals
- Analyzing the API Docs and DX Patterns in the Best Media Developer Portals 2