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:
- the available information sources (such as tutorials, conceptual and legal documentation, support, use cases, etc.),
- API docs quality criteria (such as interactivity, readability, etc.).
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.
Discover and research
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.
Information on security methodologies on Deutsche Bank’s developer portal.
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.
Erste provides a short description of its APIs and tags important information about versioning and PSD2 compliance.
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.
Nordea uses visuals to explain the workings of their APIs...
... and to to indicate who can use the APIs.
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.
ABN Amro uses a case study to show what its API can be used for.
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.
ABN Amro serves the various expectations of developers by providing call to action buttons.
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.
Evaluate
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.
Capital One starts reference documentation with a changelog.
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.
Starling provides a Trello board that shows its achievements so far and also its future plans.
Nordea shows its future plans on a roadmap.
Deutsche Bank shares its ideas about possible future APIs and asks for feedback..
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.
Capital One makes it easy to 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.
Capital One also offers a playground for developers to see what their APIs are capable of.
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.
Get started
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.
Nordea uses third-party sites to store resources.
Nordea created a drop-down menu to make selecting the resources easier.
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.
Citi has a sidebar menu to improve the readability of the getting started section.
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.
Starling provides both a web and a mobile SDK.
Implement and troubleshoot
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.
Erste is striving to provide great DX with a color coded, collapsible third column where developers can easily switch between console and examples.
BBVA chose the same structure for their reference docs with a little extra: there is also a language selector for the examples.
BBVA has a language selector too, in the third column.
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.
Deutsche bank has four categories in its contact form.
Celebrate
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.
Deutsche Bank reports on past events and recommends future ones in connection with APIs and open banking.
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.
ABN Amro organizes open banking hackathons.
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).
Capital One offer three topics to the community under resources: Learn, Read, Engage.
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.
BBVA applies a clear tagging system in its blog.
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 created a community forum with various topics.
Starling keeps in mind that developers often use third party resources: they support a Slack channel, a Trello board and Github resources.
Starling pays attention to developers who turn to third-party resources.
Maintain
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.
Saxo has a separate Release notes section, available from the landing page.
To effectively maintain a product, user feedback is indispensable. Citi provides a simple but user friendly solution for providing feedback.
Citi provides an opportunity for developers to easily give feedback.
Quality checklist
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.
BBVA’s APIs can be filtered by country and type.
Citi’s APIs can be filtered by country.
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.
BBVA offers three different levels of access to its APIs.
ABN Amro indicates limitations and pricing information right in the product overview.
ABN Amro indicates limitations and pricing.
As for responsiveness all of the portals that we checked performed very well.
The developer journey stages and great API documentation practices
| 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 |
Beyond great documentation
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!
The portals we analyzed
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:
- Introductory post
- Analyzing the API Docs and DX Patterns in the Best FinTech Developer Portals
- Analyzing the API Docs and DX Patterns in the Best Telecommunication 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
