This talk was presented at API The Docs Virtual 2021 event series on 13 July. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit our talk recaps ToC page for an overview of all presentations!
Mariano Vazquez
Engineering Director at MODO
Mariano's presentation (video recording)
Mariano's slides
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
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.