API Developer Portal — The What, The Why and The How
A developer portal is a critical part of any API ecosystem. We’ll explore what makes a good developer portal, why they’re a valuable resource for consumers of your APIs, and how to provide the best developer experience. As a case study and to help explain some of the key features and capabilities, we’ll be referencing the Nationwide Building Society developer portal throughout this article.
What is a Developer Portal?
In simple terms, a developer portal is an interface that bridges the gap between the consumers and the provider of a set of APIs. It usually consists of a website that enables developers to discover and explore the APIs, find out how to use them, get access to help and support, and potentially also test out the APIs in a sandbox environment.
The Benefits of a Developer Portal
An effective developer portal offers numerous benefits to both the API provider and the consumers. As an API provider, a developer portal can help to increase adoption of your APIs, and will help you to build a community around them. It is a tool that enables you to communicate and engage with your consumers.
As a developer who is looking to consume a set of APIs, a developer portal can help to reduce product development time, by simplifying the onboarding process so that you can hit the ground running, and by providing a centralised location where all documentation and reference material can be accessed. It also provides a mechanism for you to reach out to the provider of the APIs if you need any help or support, and to share your thoughts, queries and questions.
API Documentation
An API without adequate documentation is next to useless. To make APIs easy to use and to enable consumers to get the most out of them, the documentation that is required goes far beyond a basic interface definition and description — what is required is a full 360-degree view of the APIs. This may include onboarding information for the APIs, real-time information about the service statuses of the APIs and any planned downtime, a product roadmap showing the current features and the future planned features, sample requests and responses, and detailed information about how best to interact with the APIs. All of this information should be easily accessible from any decent developer portal. In the following sections we’ll explore a few examples of these developer portal capabilities.
A comprehensive description of the interface — this should include sample requests and responses, including error scenarios. It should also include an explanation of each field and parameter within the interface and how to use and interpret them — to add the necessary context that the consumers need to make the API usable. The example screenshot shown below demonstrates a visual representation (using Swagger UI) of one of Nationwide Building Society’s Open Banking APIs.
“How To” guides — make it easy for consumers to get started by providing help guides. These could include detailed step-by-step instructions for how to register and onboard to access the APIs, as well as other information about how to interact with them. The screenshot below shows an onboarding page from one of the Nationwide Building Society guides.
Service status information — avoid potential confusion and frustration for the consumers of your APIs by making the service status information easy to find. If your APIs require any scheduled downtime then make sure that this is communicated well in advance of the event, and consider also providing supplementary information about the specific features or APIs that will be unavailable. The screenshot below shows an example of a service availability page from the Nationwide Building Society developer portal.
Feature roadmaps — if you’re working on new features for your existing APIs (or even brand new APIs), then keeping the developer community informed of this could pay dividends for you in terms of developer engagement and interest in your APIs. It’s also important to communicate any upcoming version uplifts to provide ample time for your consumers to prepare for this on their side. On top of this, ensuring that the community are aware of the current and the recently delivered features might be a positive move.
Help and Support
If your APIs are properly documented and straightforward to interact with then any issues faced by developers should be fairly rare, however, problems and challenges can of course happen occasionally. Providing help and support to the developer community is a key function of any developer portal. Many developers like to try to solve their own problems, and so enabling them to self-serve by offering a troubleshooting guide or an FAQ could be a good starting point. This alone may not be enough though, and so consider enabling the developers to get in touch with you directly with any questions, queries or support requests — via a support mailbox, via a Slack channel, or via a “live chat” function. Interacting directly with the development community can also be an extremely effective way to build stronger relationships with your consumers, and you may receive valuable feedback or suggestions that enable you to further improve your API products.
Another effective way of providing support to your consumers is to offer a community forum as part of your developer portal. A forum can provide the ability for the wider developer community to help solve problems and issues for others, and enabling developers to interact with similar people who are using the service is a great way to strengthen the sense of community around your API ecosystem.
API Sandbox and Testing
Depending on the nature of your APIs, it might be necessary to offer an API sandbox capability via your developer portal. An API sandbox is a test environment that mimics the characteristics of production — enabling developers and testers to generate simulated responses from the APIs in a safe environment. This makes it possible for consumers of your APIs to test their apps and services in a way that reduces risk and cost. It may also provide the ability for API error scenarios to be simulated — such as high response times, latency and error conditions.
Although an API sandbox is sometimes seen as a separate capability from a developer portal, the two are interlinked to some extent, and it certainly makes sense for the API sandbox be accessible from your developer portal — as they both serve the same ultimate purpose of improving the developer experience.
At Nationwide Building Society, we offer a sandbox capability for many of our APIs. To make it possible for consumers to test their apps and services in a realistic and reliable way, we also offer sandbox test data in the form of “API Personas” that mimic real-world scenarios.
Summary
There is a lot more that I could write about here, but hopefully this has given you a solid overview. In this era of open data, APIs are becoming more and more important in an increasingly connected world. If you’re already acting as an API provider, or are considering doing so, then prioritise the developer experience by offering your consumers a great developer portal. This fantastic tool will not only act as a vital source of information and reference material for those who are looking to consume your APIs, but it will also provide a mechanism for you to build, grow and support a community.
