Merrowgate API v2
The second version of a payments API, designed from the contract up so the docs, SDKs and server can never drift apart.
client
Merrowgate
role
Senior engineer, API team
year
2023
stack
Node.js · PostgreSQL · OpenAPI
01 / problem
Merrowgate’s first API grew one endpoint at a time. The docs were written by hand, the SDKs were out of date and a large share of support tickets came from developers who had followed the documentation exactly.
02 / approach
We wrote the OpenAPI contract first and generated the docs, the TypeScript and Python SDKs and the request validation from it. The service itself is Node.js on PostgreSQL with idempotency keys on every write and a versioned changelog that customers can subscribe to.
03 / outcome
Version 2 ran at 99.98% uptime in its first year. Support tickets about the API fell by 40%, and the docs have not disagreed with the server since launch because both come from the same file.
99.98%
Uptime in the first year
−40%
Support tickets about the API
