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?

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?

Write a Developer Guide

  • 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

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

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


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.

A Jordanian foodie and a Geek! Into technology, innovation, and entrepreneurship.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store