How Candid sped up API development by 50% by going schema first

Danny Sheridan
Danny Sheridan
··

2 min read

Cover Image for How Candid sped up API development by 50% by going schema first

Background on Candid: Candid provides an API for medical billing (think Stripe but for healthcare payments instead of credit cards). They also have a UI that consumes the API.

The problems:

  1. Devs waste time writing boilerplate code. With every new endpoint, a backend engineer writes Pydantic models and FastAPI routes on the backend. And then, a frontend engineer writes the same types & networking logic on the frontend. If Candid offered SDKs to their customers, they’d have to write the same code inside each SDK. Of course, their Postman collection and API reference docs need updating too. This work is repetitive, boring, and not a good use of engineering time.

  2. Multiple sources of truth == drift bugs. Inevitably, the API’s multiple sources of truth (backend, frontend, Postman, docs, and SDKs) get out of sync. This causes runtime bugs, and the debugging costs even more engineering time.

The solution:

Here at Fern, we’re productizing schema-first API development. At Candid, it looks something like this:

  1. Define schema: When one of the backend engineers needs to change an API, they edit the API Definition (yaml files similar to OpenAPI).

  2. Generate code: They run fern generate, which generates all the Pydantic models and the FastAPI routes. Fern integrates well with mypy, so if they don’t implement the API correctly, they’ll get a compile error.

  3. Write business logic: The dev then implements the business logic and makes a PR.

  4. Generate frontend SDK: When the PR merges into master, Fern has a CI task to generate and publish a TypeScript client that is used by the frontend team. This client includes all the types and networking logic, so it’s generally a one-liner to hit the API.

All in all, it’s pretty sweet. As of 2/5/23, 95,000 lines of Candid’s backend and 30,000 lines of their frontend are auto-generated by Fern. Their devs waste almost no time writing boilerplate, and they have a single source of truth for their entire API.

Next up:

  1. API docs: Candid is going to use Fern to sync their API definition with their API docs, so their docs are always up to date.

  2. Customer-facing SDKs: Candid is going to use Fern to generate SDKs for their customers. This will speed up the process of integrating with the Candid API.

Interested in using Fern? Please reach out.

Fern is open source! Check us out on GitHub.