A developer portal for a bank's partner APIs

Context#

A bank wanted to open its APIs to business partners through a developer portal: partners sign up, try the APIs in a sandbox, get certified, go live and are charged for use. Behind it sat an existing API gateway and the core banking system.

I worked through the bank's requirements, about 165 of them, mapped each to a part of the solution, proposed the approach and the target architecture, and reviewed the bank's own high-level design against them.

What I proposed#

• One approval component. Partner sign-up, product access, go-live and changes all need approval by someone other than the requester, sometimes in several stages. One shared maker-checker component instead of an approval flow per screen.
• Provisioning that survives a failing gateway. Changes to the gateway go through an outbox with retries, and a nightly job reconciles what the portal thinks is live with what the gateway actually has.
• Protect the core. Calls to the core banking system go through a circuit breaker and a cache, so a slow core doesn't take the portal down.
• Scheduled jobs that run once. A single-run scheduler with idempotent jobs, so a job never runs twice when the portal runs on more than one node.

What the design review found#

The review was about questions the design left open, the ones that turn into incidents later:

• The session scope of the one-time-password step-up was not defined.
• The sandbox topology was not decided.
• Where fee collection ends and the bank's systems begin was not documented.
• The non-functional requirements had no numbers.
• Reports would run against the live database.

Each finding came with a recommendation, so the review could be acted on, not just read.