API-forward fintech FTW. Brex & Redocly’s two-way story
How, and why, our own banking provider chose Redocly to power developer onboarding for their first API.
Fintech might not save the world just yet, but it sure makes it a better place. Especially for the un-, under-, and over-banked among us. As the one-stop finance shop for fast-growing businesses, Brex covers all of those, and then some.
This time around we’re talking to not one, but three awesome API hackers: Pratik Tandel, Brex’s Principal Engineer responsible for building their API; Ernie Park, the company’s former leader of growth, now turned part time contractor (and sustainable farmer!); and Milo Spirig, the API’s Principal Product Manager.
- Ernie
Hearing that our users don’t think about us is the biggest praise we can get. APIs and related tools should be like electricity: ever-present and yet invisible.
Principal Engineer
Engineering Manager, Growth
Principal Product Manager
The customer becomes the customee*
* we’re coining it. Just go along with it.
- Milo
Brex is one of the world’s fastest growing fintech companies. By integrating corporate cards, business accounts, and expense software into one solution, Brex helps businesses spend smarter and manage their money effortlessly from anywhere—increasing productivity and accelerating growth.
In 2021, they realized they wanted to create an API that would enable their customers to integrate Brex seamlessly into other apps and workflows.
Taking that plunge wasn’t easy, though, since they didn’t start as a developer-focused company. “Getting this ‘cultural architecture’ right,” writes the API’s principal engineer Pratik Tandel, “is just as important as getting the technical architecture right.”
Fortunately they did get it right, as well as a few other things, judging by their docs.
Issue with the old provider
Incomplete support for the OpenAPI spec- Clunky process from spec to developer portal
- No easy way to customize developer portal theme, designs, and layouts
- Incorrectly generated documentation
Switching API docs tools
Many companies build their first API docs manually (for example, Checkr), but Brex already used a third-party tool to document their rapidly growing external APIs. Supposedly automated, this solution was however riddled with bugs and incomplete features that…
- Pratik
The thing with API docs tools is, they need to be powerful enough to let you accomplish what you dream up, but also simple and seamless enough to get out of the way.
In no time, Ernie, Pratik and team were on the hunt for a solution that would provide just that.
Looking within (... your CRM)
A lot of our customers find Redocly via search engines, recommendations or, of course, our GitHub darling Redoc. But in this case, the Brex folks didn’t have to look beyond their own CRM, as Redocly is a proud Brex customer:
- Adam Altman, Redocly’s CEO
Recognizing us as a customer, an engineer reviewing API docs alternatives decided to give Redocly a shot. Getting started was easy, and before you know it they were testing & tweaking extensively.
Getting started with Redocly
Because Brex was building their API capability and developer culture in one go, they needed as much familiarity and ‘plug-and-play’ as possible to get up to speed quickly. This is where our tech stack and obsession with OAS came in handy.
Tools that feel like home
Learning curve is an important consideration when choosing developer documentation tooling. Nobody wants to spend weeks learning a new product and sifting through a tax code’s worth of documentation (we obviously love documentation… but enough’s enough).
Fortunately for Brex, Redocly’s tech stack made it super easy to pick up and customize their portal:
- Ernie
Feature faves
⭐️
Easy UI customization- Familiar React-based stack
- Full OAS 3.0 support
- MDX markdown content
- Automated GitHub pipeline
Airtight OpenAPI
Implementing the OpenAPI (OAS 3.0) spec was crucial for Brex, as they’d opted for the code-first approach: generating their OAS spec directly from their code. Redocly worked like a charm here, because our API registry serves as a single source of truth for documentation, so whenever Brex developers add new parameters they’re reflected in the OAS definition, which then automatically updates in the documentation with no human intervention required.
- Ernie
Code-first approach
OAS 3.0 definition
Public API docs
Get started with Redocly
Build API docs you’ll be proud of for free. Try all features for 14 days, no credit card required.
Automagical GitHub-fueled docs
While customization and OAS support were important, collaboration and speed were make-or-break for Brex’s growing API team. This is where our Workflows integrations came into the picture:
- Pratik
Brex’s developer portal and API docs run in a GitHub repository forked from the Redocly developer portal starter project. The repo syncs with their OpenAPI specs, and very little configuration is needed to keep everything working.
The team writes developer guides in markdown files (including React-powered MDX), which everyone picked up quickly, as they’re not all that different from simple text documents. All changes are submitted through a typical PR process, and the GitHub integration makes it possible to validate and preview changes before submitting them to Redocly. Once the changes are merged into the main branch, Redocly picks them automatically, builds the docs, and deploys them to the production site. Changes can also be tested locally with just a few yarn commands.
Lightweight flow; lightning-fast iterations
Brex accomplishes an extremely quick update lifecycle for their docs, primarily owing to Redocly being lightweight and simple enough to test and push small updates without overhead:
4 min
Time from pull request merge to production
4
Production deploys per week
- Ernie
How Brex is using Redocly
GitHub Workflow
Automated pipeline from GitHub to docs, reducing friction and development hours.
We’ll keep banking on APIs
Pervasive automation is perhaps the greatest achievement of our era, and the API economy is its most powerful driver. The new Brex API is a great step forward in this direction, and we are honored to be part of their API journey as both providers and customers.
Automation superpowers are the reason we chose Brex as our finance provider at Redocly. Brex and fits into our workflow perfectly, just like we fit into theirs:
Engineering Growth at Brex
But there’s more than automation to this story. There’s a unique kind of synergy – or more simply, ‘magic’ – when technology companies join forces as one another’s customers. Camaraderie, developer-culture spillover, and pride, among many others. In the words of our CEO and co-founder:
Redocly CEO
We’re with Brex as they continue their API-forward company. As you innovate the finance stack of the future, we’re here to keep it neatly documented for everyone to enjoy and build upon.