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.

Day-to-day, we don’t think too much about Redocly itself, which is exactly what we want! While we use it often, it feels just like using any other engineering tool that is very familiar to any front-end dev, which is great.

- 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.

The software and services financial stack engineered for fast-growing companies.

  • Remote-first & global
  • Fintech
  • $12.3 billion valuation, 1000+ employees
  • Developer portal, GitHub Workflows, Reference docs
Pratik Tandel

Principal Engineer

Ernie Park

Engineering Manager, Growth

Milo Spirig

Principal Product Manager

The customer becomes the customee*

* we’re coining it. Just go along with it.

As we were having issues with our existing solution, one of our engineers spotted that Redocly was a Brex customer and looked into 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

  • markIncomplete support for the OpenAPI spec
  • markClunky process from spec to developer portal
  • markNo easy way to customize developer portal theme, designs, and layouts
  • markIncorrectly 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…

made it so we had to manually intervene at many steps which defeated much of the purpose.

- 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:

Brex is our all-in-one finance platform. We manage Redocly's cash flow, investor funds and corporate spending from our Brex account. It comes with built-in expense management, bill pay and the industry's best rewards.

- 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:

Redocly has made that much easier as it is React based and on a stack that’s very familiar to all our engineers and designers. It’s basic React, CLI tools, CSS and some well-documented config.

- Ernie

Feature faves

⭐️
  • markEasy UI customization
  • markFamiliar React-based stack
  • markFull OAS 3.0 support
  • markMDX markdown content
  • markAutomated 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.

The main thing is that our API reference is extremely easy to update. Engineers just worry about the code. Right now I can keep the docs up to date with very minimal work.

- 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:

The main deciding factor in choosing Redocly was the ability to build an automated pipeline from GitHub to customer-facing docs. This was critical to reducing friction in our developer flow.

- 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

We can push changes even if they’re very small and not have to do large, heavy-handed releases. This means docs stay fresh and we can iterate quickly.

- Ernie

How Brex is using Redocly

Developer Portal

GitHub Workflow

Automated pipeline from GitHub to docs, reducing friction and development hours.

Secure multi-auth

Developer Portal

On-brand developer onboarding with deep level React customization.

On-premise

Reference Docs

API docs built and updated directly from OpenAPI definitions.

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:

Ernie Park

Engineering Growth at Brex

Overall, the best thing about using Redocly is that it just works the way you expect it to. It fits seamlessly into our flow just like any other engineering tool.

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:

The big bet of the APIs economy is making every technology a multi-way street. By melding our service both ways with Brex, we get a chance to learn how to create this future faster.
Adam Altman

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.

Superpower your API lifecycle with Redocly