Developers

APIs: the Love Language of Technology

Erin
February 14, 2022

A few weeks ago, my colleague Evelyn made an off-the-cuff, wry observation about building technology products:

“I think APIs should be considered the love language of technology 💝”

Briza has always taken an API-first approach to software development. We’ve done our best to build an API that not only helps us build great user experiences, but also helps you build great experiences.

Since Valentine’s Day is today (and who doesn’t love an awkward seasonal tie-in?), let’s take a look at the ways we at Briza have built an API we hope you’ll love.

Love Languages

The phrase “Love Languages” comes from a 1992 book about relationships. The idea is that people have different ways to express or receive love: spending quality time together, giving gifts, and so on.

Bringing things back around to Evelyn’s observation, each software engineer looks for specific things in the APIs they use: usability, performance, and so on. Every developer at Briza came here with memories of great (and not-so-great) APIs we’ve experienced. We each have hard-won knowledge of how APIs tick, and we’ve put that knowledge into practice here.

In this article, we’ll talk about some of the things Brizans appreciate about a great API — the love languages of APIs, if you will. There are a ton of topics to choose from; to keep things brief, we’ll focus on just five love languages:

  • Documentation
  • Reliability
  • Descriptiveness
  • Usability
  • Consistency

Documentation

Our favorite APIs are ones where the documentation helps us get started quickly. Where do we get our API key? How do we authenticate? What’s the first “Hello, world!” request we can send to make sure we’re using it correctly? What’s the first request we need to send to use the API for real? What does the end-to-end flow look like? The docs provide crucial answers to these early questions.

Because we’re passionate about great documentation, our developers work hand-in-hand with our documentation expert, Geetha. Her detail-oriented approach ensures that every endpoint, every parameter, and every data field has an explanation, allowable values, and meaningful examples. Moreover, we have focused articles on specific topics, such as authentication, webhooks, and so on.

Reliability

We want our API to be available to you at all times. We want it to work well. We want each operation to work the same way each time you perform it.

Accordingly, we monitor our systems for all kinds of potential problems. Whether it’s something out of our control (such as a network issue between us and our carrier partners) or something we can directly fix, we hold ourselves accountable for providing a good experience for you.

We aggressively load-test our systems, speed-running insurance applications thousands of times faster than human fingers could ever type in their business details. We develop every feature with an eye toward performance. And we maintain a public status page where you can find out more about any ongoing issues or planned maintenance windows.

Descriptiveness

When we think about descriptiveness, our minds go to documentation first. And our docs are indeed vividly descriptive, but we didn’t stop there.

We also aim for every data field of every API payload to be descriptive. Even if you’ve never seen our API before, I’ll bet you can guess what the following fields in our application payload mean:

{

  "status": "created",

  "id": "d78fda3f-f5c5-413d-a929-68872875bd68",

  "questionnaire": {

    "version": 2,

    "layout": ["..."],

    "questions": ["..."]

  },

  "answers": {},

  "timeZone": "Etc/UTC",

  "updatedAt": "2022-02-10T22:41:35.500Z",

  "createdAt": "2022-02-10T22:41:35.500Z"

}

We agonize over these field names. We build applications on these endpoints before we release them to developers, giving us time to make changes if something isn’t usable. We want each individual endpoint to make sense on its own, and we also want them to fit into a coherent whole.

Usability

We want our API to be easy to use well, and difficult to use incorrectly. If an insurance application is missing an answer to a question, we don’t just tersely refuse the application. We say which answers are missing, so that you can supply them and try again. If a carrier has declined to insure the business, we break down the reasons why: weather risk, a gap in the underwriting model, etc.

Consistency

We strive to make the overall flow of the API consistent. Each step should follow naturally from the previous one.

Let’s make this idea concrete. To help people apply for insurance through Briza, developers need to create four items in sequence through our API:

  1. Pre-application (a few basic questions about the business)
  2. Application
  3. One or more quotes
  4. Policy

Each time you create one of these objects, you get back a unique ID to refer to it. You use that ID to answer questions for that step (business info, quote coverage questions, etc.). You also use it to kick off the next step. Each quote needs an applicationId, each policy needs a quoteId, etc.

Once you’ve done one step of this process, you know how to complete the remaining steps because they work the same way. If you miss a step or get something out of sequence, our error messages will point the way back to the happy path.

An API we hope you’ll love

There’s lots more to building an API than just these five things. But we hope this has given you a glimpse into how we obsess over the details. We’ve built an API that we’re proud of. Much more importantly, we want you to love it too.


Erin

Erin leads the Turbine Team at Briza. Her team is responsible for building the Briza API into a world-class product. Before she came to Briza, she made big architectural changes safely to complex systems at companies like Stitch Fix, New Relic, and Tektronix. Erin’s favourite engineering problems to solve are big, thorny, legacy system snarls. She has written or co-written five books on programming, most recently Effective Testing With RSpec 3. When she’s not behind the keyboard, you can find her race walking, coaching athletes, and playing board games. Erin lives with her wife, their youngest child, and a cranky Corgi mix who’s still getting used to Canadian winters.

Related