Analyzing the API Docs and DX Patterns in the Best Banking Developer Portals
Breadcrumb
- Home
- PronovixBlog
- Analyzing The API Docs and DX Patterns In The Best Banking Developer Portals
PSD2 and a swarm of Fintech guerilla competitors are shaking up the banking sector. A large number of financial institutions decided to embrace the change, and to execute an Open banking strategy. As a direct result, a lot of new APIs and developer portals for banking services are now available on the public web.
From the numerous developer portals we found, we’ve selected some of the best portals that demonstrate the innovations and best practices to enhance developer experience in the banking context.
We will evaluate along two main areas:
You can read more about the background to these two concepts and why we chose them in our introductory post.
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.
How can this portal help me solve my specific task?
The first step is defined mostly by the landing page. At this stage users need to be able to decide whether the API(s) can be the right choice to solve their problem.
A basic requirement of a banking API is maximum data security, so most banks highlight this information on their landing pages. Deutsche Bank and Erste for example assure their users right on the landing page about the security methodologies they use.
In most cases a bank offers several APIs, so they often define themselves a hub of APIs, and they try to give a clear overview of their available products. Erste provides an example on how this can be done, by presenting short, clear descriptions on their APIs in plain English, while also marking the most important features, like in which countries the API is available, is it compliant with the PSD2 regulations and tags on the versions.
The general descriptions of the APIs can help users select the product they are looking for, but they usually need additional information to decide whether they are making the right choice. The overview pages of Nordea help this decision with visuals on the workings of the API, and they have a clear customer type focus by indicating the possible users.
Instead of visuals, ABN Amro uses a case study to show an example on what their API can be used for and they also provide information on the availability and pricing.
There are several different stakeholders of an API throughout its lifecycle, but developers are arguably the main audience of developer portals. However, developers are not a homogeneous group, they have different backgrounds and different expectations. Meng et al. talk about experienced/less-experienced, and code-oriented/concept-oriented developers as the extremes, and a lot of portals seem to keep this distinction in mind. Both Erste and ABN Amro provide call to action buttons that address these different target audiences.
Less-experienced or more concept oriented developers can check the documentation first, while more-experienced or code-oriented developers can go straight to trying out the API.
Can I trust this organization’s commitment to its APIs?
After getting an overall idea, users usually want to make sure that they can trust the organization and the APIs it offers, and they want to know these APIs more thoroughly by testing them. Information on versioning is so important that many portals indicate it on highlighted places. Erste puts a tag marking the version in the API catalog and it also starts the references with a changelog just like Nordea and Capital One do.
PSD2 put the banking sector in a position where they quickly have to adapt to the latest innovations. Many of the banking developer portals have been launched recently and many of the APIs are in different stages of testing. Creating trust by showing how they have been taking care of the APIs is usually not an option in this industry. However, future plans, if presented well, can also act as trust signals. Nordea and Starling use Trello roadmaps to share their plans about the future, while Deutsche Bank even shares its ideas about possible future APIs.
Providing safe environments where users can try out and test their applications can help a lot in convincing them about the value of the APIs. There are different types of demos that can help users understand the operation of an API, but on banking portals the most popular choices are sandbox and playground environment. As data security is central in this field, sandbox is usually a first choice as it provides the most control over data access, while still allowing to test. Hoping that developers will actually decide by the API after trying it out in the sandbox environment, both Erste and Capital One makes it easy to simply switch between sandbox and production mode.
Besides a sandbox, Capital One also offers a playground. The difference is that playground is more for demonstrating what the API is capable of, while sandbox gives the developer an opportunity to test the API with mock data mimicking real ones.
Built in console and Postman are the other two popular testing options among developers, and they can later also be used for production. ABN Amro provides a downloadable Postman collection to make testing easier, while BBVA highlights that using Console is an easier option.
Where do I begin?
The aim of the resources in the Get started step is to make starting the actual work with the API as frictionless as possible. Erste provides a great example on its landing page on how this stage can be improved by showing each step of the getting started process in animation, marking even the necessary time.
Nordea has an unusual approach to the getting started resources. It uses third-party sites to help developers at this stage. Training videos are available from Youtube, there are downloadable Swagger and Postman files while code samples and examples are stored on GitHub.
On a developer portal there are several methods that ensure data protection and this is especially important in case of banking portals. The most commonly used security measurement on the portals we analyzed is the combination of an API key (also called client ID or secret key), OAuth with JSON Web Tokens and Open ID. Clear instructions with examples about the authorization and authentication process is a must at this step. Both Erste’s and Capital One’s developer portal contain numerous screenshots to support the textual description of the process. Even without screenshots, the readability of the getting started documentation can be improved by using a sidebar menu, like Citi or ABN Amro do.
Starling has a user friendly solution to make getting started easier by offering both a Web and a Mobile Starter Kit SDK to its users.
Do I know everything to make this work?
The reference docs on Erste’s portal show that it strives to provide great developer experience. It has a collapsible third column, where not only the console is available, but developers can switch to examples with only a click. The parameters are also colour coded to further improve scanning.
BBVA chose the same structure for their reference docs with a little extra: there is also a language selector for the examples.
FAQs and knowledge bases can be effective support at this stage, and the way they are presented is also significant. The previously mentioned third-party resources from Nordea can be very useful for developers. However, registration gives you access to even more support options.The whole support section is searchable and the FAQ section has several smaller topics. Our research showed that some developers tend to ask their peers first, so having a community section seems to be a good idea. We have already mentioned the importance of PSD2 in the industry, so it is a great idea on Nordea’s part to include a PSD2 guide in their support documentation. And if a developer needs more help there is the option to create a ticket and ask for help.
Deutsche Bank improved its direct support, by creating four categories in their contact form - there is a possibility for requesting a feature, reporting a bug and making a general inquiry or a business one.
Will they care about my work?
There are several ways to show developers who invest in an API product that the API provider appreciates their efforts. In addition to creating a feeling of appreciation, building a community around an organization’s APIs is a great opportunity for viral marketing. Besides having a newsletter, Deutsche Bank focuses on building a community by attending and organizing events: they inform their users about these events under the News & Events section, and they also recommend future events they will attend themselves.
ABN Amro also organizes a hackathon to further foster their community. In case of a new developer portal (ABN Amro’s was launched in November 2017) in a new field (ABN Amro is the first Dutch bank to provide access to a developer portal) hackathons may be a great opportunity to make developers more aware of your product.
Capital One pays great attention to community building, and they offer more options on their portal. Under Resources there are three categories: Learn (for developers, from experts of various fields), Read (a blog with articles and video interviews with API experts) and Engage (offering hackathons and webinars).
BBVA also has a Resource section consisting of several topics. The Blog has a clear tagging system, there are downloadable Ebooks, and the Events section recommends several encounters in connection with APIs and open banking.
Starling chose to have a well-designed and structured community forum as their way of providing space for the community. The various categories give an opportunity for developers to share success stories but also to ask for help if needed.
Starling keeps in mind that developers often use third party resources: they support a Slack channel, a Trello board and Github resources.
How hard will it be to keep this running?
We previously mentioned that the changelogs at the beginning of reference documentation are important trust signals. They show not only that the organization looks after its APIs, but also that the provider pays attention to informing the users about the changes. Saxo highlights this resource even more by creating a separate Release notes section, clearly visible right from the landing page.
To effectively maintain a product, user feedback is indispensable. Citi provides a simple but user friendly solution for providing feedback.
Based on our research we found that developers find some aspects to be of crucial importance for the quality of the API docs.
Most of the portals that we checked provide various options for testing the APIs, but we can highlight Erste’s documentation with its three column structure, where the easy switching between the examples and console maximizes the interactivity.
Erste and BBVA enhance the readability of their developer portals and offer most of the content in Czech and Spanish respectively. Capital One provides a great example for consumability by creating a copy button on each code sample.
BBVA and Citi, the two multinational giants are good examples of how searching can be made easier. Their APIs’ catalog can be filtered by the countries where the APIs are available, while in case of BBVA there is even a possibility for fine tuning the search and choosing the type of the API.
In connection with the information about the service we have already mentioned the example of putting the changelog at the beginning of the reference docs. Another crucial information about the API is the pricing and business models behind it. BBVA offers three different access levels to their products from sandbox to full access, with clear descriptions on each level.
ABN Amro indicates limitations and pricing information right in the product overview.
As for responsiveness all of the portals that we checked performed very well.
Stage | Think about |
---|---|
Discover | Landing page Information on security methodologies Visuals on the working of the APIs Case studies |
Evaluate | Information on versioning Changelog Roadmaps Future ideas Sandbox & playground |
Get started | Animations Training videos Postman collections Code samples and examples SDKs |
Implement and troubleshoot | Reference docs FAQ section Community section |
Celebrate | News & Events Blog Hackathon Ebooks Third-party resources |
Maintain | Changelog Release notes |
Even the best APIs need a well-designed developer portal, to see the adoption they deserve. Developer portals need to address various audiences, developers with different backgrounds, marketing, sales, CXO, etc. The trailblazers of the API industry are developing DX innovations day by day from which we can all learn from. We think that by collecting some of the best practices we can help the industry accelerate its own development. We selected portals that have been talked about recently but our list is far from being exhaustive, so we would be happy to hear about your ideas in a comment below.
Don’t forget that the nomination phase for the DevPortal Awards starts in June. Let’s applaud together the world’s best developer portals!
For this part of our series we brought examples from the following developer portals:
Thank you so much Kathleen De Roo for the guidance and Laura Vass for the editing!
Posts in this series:
Mónika started at Pronovix as a content writer. While doing research for the Pronovix blog posts she got fascinated by Information Architecture and UX. Apart from continuing her research into devportal best practices she works with clients in the information architecture phase.
Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.