Write your APIs like you write a movie

If you have built APIs, then by now, you are already familiar with the practices of how we typically build APIs:

• Code first API approach
• Contract first API approach

But there is one that I absolutely love, and I think is where APIs become art… Developer Guide first approach.

“The purpose of a storyteller is not to tell you how to think, but to give you questions to think upon.”

— Brandon Sanderson, fantasy and science fiction writer

Why a “Developer Guide” first approach?

I have been building API products since 2005, and having designed and built good and bad APIs, I now have a belief that API design is a form of art. I believe that a good API is an API that tells a story, just like a movie; they have a plot, characters, a viewpoint, a dialogue, a style, and most importantly, a beginning, middle and an end.

A well designed API has all those elements, and if you are building an API based product and want to ensure your APIs are adopted and are differentiated, then you have to start thinking about the stories your APIs tell.

And what’s a better way to tell your API story than a developer guide?

How does this work?

Well, here’s my approach to building APIs

Write a Developer Guide

I start my API design by writing a developer guide. For me, a good developer guide has the following:

• a plot: in an agile world, this one is easy to translate, this is the user story behind the API. It’s what the API helps the characters achieve
• characters: the users, or personas of the applications that are built using the APIs. Think of the customer, not the developer that will consume the API. The developer is the critic, not a character in your story
• a viewpoint: the viewpoint is how you tell your story — the lens by which the reader travels through the API. Tell your story in the lens of a customer of an app using your API.
• a dialogue: the dialog is how a customer’s journey travels between the different operations in your APIs. It shows the purpose and the value of your API
• a style: your API style of writing is how you define your APIs resources, parameters and the naming and value conventions. A good story has a consistent and purposeful style
• a beginning, middle and an end: start the user guide with a trailer of the plot — what the customer journey is. The middle is how you explain the narrative of the journey and the transition between the APIs, and conclude with a happy customer completing a journey, add some suspense with sequels and alternate endings.

Write an OpenAPI Spec

This is where a typical Contract First approach API design begins, and the OpenAPI Specification is the most adopted standard for of defining API contracts.

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

These are the writers, directors and producers vision of the movie. They define the characters, the scene, the clothing, etc. They help everyone involved in making the movie during the filming process.

This is the script, or the contract that helps you select the actors and location for your movie; the tech stack for your API. Once this is defined, this is what you share with all the parties involved so they can start the actual work.

Of course, as you write the OpenAPI spec, you might have to make slight changes to your user guide. That’s a natural part of the process.

Write a Consumer-Driven Test

When it comes to build API products, I prioritize and prefer consumer-driven test approach over any standard test driven development approach. Unit Tests, Integration Tests, Test Coverage are all focused on the API developer, rather than a consumer. And when you build API based products, your consumer comes first.

Whether building private or public APIs, consumer-driven tests are what guarantees and validates that my APIs have been built and satisfy the defined and agreed contract, and that for me, is the exit criteria that counts and the most important checkpoint for me to rollout any changes to the APIs.

Write the Code

This is where you make your API, or movie. And most likely, this is what the people involved in making it enjoy the most. But remember, without a good story to tell, the actors, the director, the location all won’t matter.

Iterate

Like a good movie, there will probably be a sequel, or a remake. Just please, build a Godfather trilogy, not a Scream series.

When you build an API based product, what makes or breaks it is how well the story is told, and how do you tell your API story? In a developer guide. No one will care how many APIs you have, or what cool tech they run. If the story is not told right and is not captivating, you will fail.