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
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
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.
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
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.