Devportal Awards 2019 is open for nominations. We are looking forward to your thoughts on public-facing API developer portals!

This article is the third in the series. We wrote it to serve with an overview of the nomination categories with background explanations and examples. The article walks through the evaluation criteria.

Posts in this series:

  1. Best Accessible Devportal and Best Internationalized & Localized Devportal
  2. Best API Business Model and Best Decision Maker Documentation
  3. Best Onboarding and Best API Reference Documentation
  4. Best Post-integration & Maintenance Support, Best Policies & Terms of Use and Best Community Spotlight and Outreach
  5. Best New DX Innovation, Best Design, and Best Overall Developer Portal

How can you attract and convert new users through your developer portal? How can you make sure your customer developers can easily onboard and integrate with your APIs?

In our previous article, we focused on what can help you, as a user, to decide if a devportal provides you with the solutions you are looking for. In this article, we will look at what comes next: how can you actually start using the devportal and its APIs? How does the authorization process work? How can you run tests? What is needed to begin implementing? How can you accelerate your work?

In this post, we will focus on the categories of Best Onboarding and Best API Reference Documentation. It highlights the criteria that we think define these categories and we showcase how last year’s nominated devportals stood out.

Best Onboarding

This category is for developer portals that clearly show what their APIs are about, how they work, how developers can start integrating and where they can find resources.

Onboarding information addresses the second and third stage of the downstream developer journey:

  • Evaluate: How can I, as a user, test the API? Can I evaluate the API before or after logging in?
  • Get started: How easy is it for me, as a user, to register? How can I start using the API that I selected to finish my task? What documentation types are available to help me find out how everything works?

Get started with the devportal & its APIs

The character of your devportal

What authentication and authorization processes do your users need to go through to start using your devportal?

  • Do you ask users to register and be logged in before they can access documentation and features?
  • Do you provide try-out options before registration?
  • Do you provide free try-out options after registration and authorization?
  • Do you ask users to go through a staged registration model, where they get access to docs and features depending on their authorization status?

When you communicate the registration process clearly (What will happen when? What do you get in return for what?), you help to set your users’ expectations correctly.

GoodData.UI asks users to register (through a short form) before they can enter the live examples.

Erste Bank’s overview page features a visual of how to get from registering into production.

Erste Bank gives an overview of how to get started and provides descriptions on how to use the sandbox environment, including code examples.

Sendgrid helps users to know about API key characteristics via highlighted sections.

According to the reciprocity principle, users will share personal data more easily if you provide them with information upfront. Evaluation tools (such as samples and demos) and testing tools (such as try-it-out options, a playground, an API explorer, a sandbox environment) can help to give your users a taste of what you will offer them in production. Business requirements and security restrictions influence what you can provide when. Read more on this topic in our article on developer portal user engagement.

The Orange lists the steps needed to start using the developer portal and its APIs.

API docs & supporting docs

Onboarding documentation can take different forms, e.g.:

  • how-to guides, topic guides and tutorials that address onboarding with a clear step-by-step method,
  • dedicated blog posts and use cases that explain what a specific API is capable of,
  • code samples that provide examples,
  • SDKs that provide all the necessary information to use the API (e.g. in a specific coding language),
  • conceptual documentation that explains business-specific language,
  • other resources, such as visuals that show the API architecture.

Nexmo makes sure that developers can jump into the onboarding documentation easily: they make doc types, such as tutorials and SDKs directly available from their overview page. On top of the page there’s a direct link to a “Try it free” section (which requires registration). The tutorials feature tags that can list Nexmo’s APIs based on available programming languages. The cards provide descriptions of what the APIs are capable of.

Best API Reference Documentation

This category addresses the heart of developer experience:

  • How can devportals improve on API reference documentation?
  • How do they integrate with “try it out” and sandbox functionality?

In this stage of the downstream developer journey, it is important to figure out whether you know where to find every bit of knowledge that you need to make things work.

Sendgrid provides easy access for 1. developers who would like to enter the references immediately, and 2. developers who would go through the onboarding information first.

Elements that enhance the Developer eXperience

There are lots of features that can make the life of your implementing developers easier. Some examples are:

  • highlighted code,
  • options to test the API (e.g. via Postman, a built-in console or the try-it-out option in the Swagger UI),
  • the possibility to leave comments,
  • buttons to copy sample code,
  • collapsible columns,
  • a programming language selector,
  • interactive links,
  • an easy way to switch between testing and production environments,
  • 1-, 2- or 3-column-style,
  • troubleshooting options (e.g. through an error dictionary),
  • explanations for classes, methods and parameters,
  • information on versioning.

Nexmo’s references are displayed in 3 columns. The screenshot shows their error dictionary. Note the sidebar menu on the left, the example response and a coding language selector on the right.

KPN provides the possibility to open the API references in SwaggerHub and in Postman.

Erste Bank’s reference pages enable an easy switch between the (collapsible) examples / console column via a button on the right.

The Pipedrive devportal users can send test API calls to try out functions by providing values in the “Test endpoint” fields and clicking the button on the Swagger UI. Note the possibility to “star rate” the endpoint.

Altogether, it is important to strive for “self-service support inspired” resources on your developer portal: if you make documentation intuitive and easily findable, your users will need less help from outside to solve problems. Good onboarding documentation will make sure you attract new users and convert the people who are visiting your developer portal. API reference documentation, when done well, will provide your (mainly developer) users with the information they need to finish tasks. Does your devportal provides examples that underline these requirements?

DevPortal Awards 2019: How to nominate your developer portal

What is the goal of the DevPortal Awards?

The goal is to recognize public-facing developer portals that show great examples in eleven different categories and to find the developer portal that provides the best overall experience.

Why should I nominate my developer portal?

By nominating a portal you can draw the community’s attention to it and acknowledge the work of the people behind it.

How can I nominate my devportal?

Please fill out the nomination form!

Who chooses the winners?

The winners of the 11 nomination categories will be chosen by the Awards Jury in October. In the Best Overall Developer Portal category two winners will be selected: one by the jury and one by the community via public voting. The portals nominated in any of the 11 categories are running for the Best Overall portal automatically.

How can I stay up-to-date and get notifications?

Sign-up to the DevPortal Awards newsletter and receive info on nomination and voting, nominee and jury news, and details on the gala event.

This article was edited by Mark Winberry. Many thanks to Anna Antal for the background research!

About the author

Kathleen De Roo

Information Architect, Technical Content Writer

Kathleen started as a technical content writer, responsible for doing research and writing on developer portal aspects. As an information architect, she helps clients find out how to align business goals and user needs with the knowledge we gathered about devportals.

She holds master's degrees in history and in archival science & records management.