Belvo’s core product is a set of fintech APIs that connects users with their banking, financial, and fiscal data. Ours is primarily an API product, that is, a product that is consumed through API endpoints and that is used as a building block for third-party products. Like the majority of API products, Belvo is a B2B offering.
Building an API product poses a few peculiar challenges. The most obvious is arguably the initial integration efforts required to use it. When we see Belvo adopted by a new company, we see a third-party product development team focused on integrating Belvo with their product, which is normally something that involves scarce resources such as engineers, PMs, designers, and precious roadmap time.
Given how critical this initial integration process can be, it must go as smoothly and efficiently as possible. In addition to the API itself, a good API product must be complemented by tools, resources, and documentation to minimize any potential friction and provide developers with total autonomy.
This post covers what we believe is the basic API product toolbox, which we have implemented since we launched Belvo in 2020. That is, the basic tools that we baked into Belvo beyond the API itself.
Self-service developer experience
When we started building Belvo, we sat down to understand what were the most important resources that we would need to bake into the product from ‘Day 1’ to make the integration process as smooth as possible. We looked at companies such as Stripe and Twilio and tried to understand what they had in common and how they delivered such great developer experiences.
The one thing all great API companies have in common is their focus on self-service developer experience and their commitment to self-service tools and processes.
No engineer likes to go through multiple hoops and sales calls to get access to an API endpoint. Having a great self-service experience can make the difference between integrating a product like Belvo in a couple of days and turning it into a multi-month ordeal.
Building a true self-service developer experience involves facilitating operations such as setting up a test environment, downloading SDKs, generating API credentials, accessing documentation, generating API analytics, and developing error debugging facilities. Everything has to be accessible through a developer portal, easily discoverable, and not gated by any lead generation form.
High-quality documentation
In the spirit of self-service consumption, the documentation of an API product is one of the first things that needs to be built along with the API itself. Good API documentation needs to be developed on two different axes: development guides and API docs.
- Development guides usually cover broad topics such as “getting started” or “how authentication works” in a guided, tutorial-like fashion.
- API endpoint docs, on the other hand, are reference materials containing detailed information regarding each API endpoint, covering inputs, outputs, and error and success codes.
One thing that we have learned on our journey is that while engineers and PMs can write documentation, they are not content specialists, and they’d prefer to jump to the next feature rather than obsess over documentation quality. Onboarding technical content writers who focus solely on documentation was an important step forward for us to improve our documentation quality.
We’ve also found that, in addition to development guides and API endpoint docs, developers value content such as sample quick-start applications, code samples, and above all, a Postman collection covering all the API endpoints with prepopulated parameters and configuration values. Having a Postman collection ready to run also allows us to provide support on top of a well-known client implementation, as opposed to digging inside each specific client integration.
SDKs and libraries
Most API products can be accessed in two ways: either directly through raw API endpoints (such as REST, GraphQL, or other solutions) or an SDK or library.
Building SDKs for many programming languages has a cost, which can be even more substantial if your team isn’t specialized in the programming languages you want to build support for. At Belvo, we’ve found that our API call success rates increase by as much as 30 percent when an SDK is used instead of the raw REST API. This has provided us with a solid reason to invest in SDKs in various programming languages.
We believe that good SDKs have three main properties:
- They should reflect the needs of your client base. To do so, we frequently ask clients and prospects what programming languages they would like to see supported, and we keep a prioritized list of programming languages to support.
- SDKs should be idiomatic. In other words, they should take advantage of each programming language’s features and typical constructs.
- SDKs should be open source because software engineers want to be able to control the SDKs they pull into their projects, inspect their source code when debugging, and maybe even change some of its behavior. As a corollary, SDKs should be available through package managers such as npm, PyPi, or RubyGems so that they can be easily included in a build pipeline like any other project dependency.
A sandbox environment
A sandbox environment allows developers to try an API product out safely and easily, without impacting production resources. A sandbox environment usually has its specific URL and will come with some sort of limitation, such as the number of API calls or some hard-coded response values.
One additional functionality that the sandbox environment can offer is the ability to programmatically reproduce both real-world conditions and simulated error situations and various corner cases.
For instance, when you pass certain specific parameters to Belvo’s sandbox, the environment will trigger synthetic error responses, return specially crafted mock data, or execute other specific business logic that might be difficult to reproduce reliably otherwise.
The sandbox environment is as important as production. One might argue that an error in a sandbox environment is much more costly than in production. That’s because the sandbox is often used by prospective clients to evaluate whether to use a certain API product or not and therefore each error can be a deal-breaker.
A developer dashboard
Especially when dealing with large numbers of calls, it’s important to provide developers with a place to understand how their applications are behaving and how their API calls are performing, including response codes, payload debugging facilities, and other technical information.
A developer dashboard has become common across API products. This is something that an API platform has to offer so that developers don’t have to reinvent the wheel and roll out their own API analytics and debugging tools.
There are a few basic features that a good developer dashboard should offer:
- Credential handling and environment configuration
- API analytics
- Error troubleshooting
- Interactive debugging (e.g., generating and reacting to synthetic events)
We need your help 😊
At Belvo, we’re continually trying to do more to improve the developer experience of the platform. We’re passionate about creating a platform that is easy to use, offers the right tools for the job, and gives developers the autonomy they need to develop quickly.
If these are topics that spark your interest, feel free to check out our careers page. We’re currently hiring across several positions.
