Mariano Vazquez - How to develop an API ecosystem for the fintech industry from the ground up

The Modo mobile app is a digital wallet with a twist: to integrate all your bank accounts in a single application, but Modo is also a platform for integrating the app’s functionalities in the banks’ mobile applications. It is possible to pay directly from the bank account instead of using a credit card.

How to design a solution

Laying out all the use cases that need to be solved.

• OpenAPI and Swagger is used as the common place for our API ecosystem docs

• The first API specification was designed in SwaggerHub that covered the initial use cases with 3 endpoints:

  • Onboard users to the platform in a secure way
  • Send & receive money to & from friends
  • Pay with QR code in a shop

Benefits of SwaggerHub:

• automated docs portal within 2 months by writing only the OpenAPI Specifications
• having a mocked service which saves money and time when integrating with multiple 3rd party services
• free code generation

Lessons learned

Before production

1. Something missing or wrong? Break everything!

You can make breaking changes if you are not in production. It is only a matter of communication as other teams are integrating while developing this thing

2. Integrate as soon as possible is a good way to learn

Integrating with multiple APIs at the same time, not only creating a new set of APIs, not only creating a platform from scratch, but also the technical teams were creating their own APIs inside their own VPNs

After production

1. Top-down approaches are great for starting the conversation, but harder to maintain

• using Swagger as the main documentation/single source of truth was not enough
• starting with the design then implementing the code was not a good idea

2. Moving toward a new approach: first having the documentation in the code

• it is easier to understand what the APIs are doing and to keep them up-to-date
• when you have a breaking change, it is easier to create a new endpoint in your code and deploy the documentation right away from your code

3. Having 2 versions of the API was not enough: 3 versions of the API living together at the same time is reasonable

• an unstable version with a couple of teams that sponsor that new feature
• an_ active/stable_ version that most of the banks are using
• a maintenance version for the banks that are not ready to migrate, don’t have the time, or prioritizing their own roadmap - a year of life is planned for this version before deprecating it

4. Open & Bidirectional and automated communication (as possible)

• having SwaggerHub and a common contract is useful, but it is not bi-directional or open as hoped for
• mixing more things to create a transparent and bi-directional communication with all the partners (automating email communications, using Slack messages instead of just email)
• applying the same practices to the rest of the teams that are already very useful in tech or engineering teams helps communication when you have multiple partners waiting for information

5. Dogfooding: test our own stuff

• inhouse testing instead of releasing things and having the partners to test them
• creating a mocking service: an API that implements the contract with the partners
• putting on clients’ hats reduces friction and could prevent architectural decisions that are hard to implement or maintain on the client's side

We are today building the foundation of a live ecosystem evolving together: trying to add the human part of the mix, and that we are together in this.

Plans

• Key stakeholders as feature champions (beta testers)
• Newsletters: From emails to reduce audiences to all
• Improved ecosystem: notifications via events
• Public roadmap & organize work with initiatives/themes