Your Guide to The Language of API Design

For new subscribers and visitors to API Design Matters, this guide will orient you to the The Language of API Design series. This series is dedicated to a key topic of API design: expressing API ideas and concepts using the OpenAPI specification—the language of APIs.

Below are abstracts of the articles in the series, and also a brief summary of the sample API that we develop within the series. I encourage new readers to “go back to the beginning” to establish the context of (and the fictional API example used throughout) the series. While I’d love for you to read all the articles in sequence, skimming them will provide some context for understanding later articles.

The Language of API Design

Today’s software landscape demands software systems that can talk to each other. Interoperability and open access to data and services is key to (sometimes phenomenal) success. Application Programming Interfaces-APIs-are at the heart of this revolution, from enabling all the apps on your phone to reinventing companies and entire industries. Forbes explained Why The API Economy Is The Web’s Next Phase and Nordic APIs described the role of Open APIs across six diverse industry and government sectors. But it’s clear APIs are not just the “next wave”-they have been the wave for years. The most successful technology companies rely on APIs. Knowing how to design build APIs can reboot your career.

Published: February 8, 2023

API Design First is not API Design First

To kick off The Language of API Design series, we will take a brief but important diversion from the OpenAPI Specification and it’s unique but powerful language of API design. Our detour will focus on a different sort of language: the ubiquitous language of Domain-Driven Design.

Published: February 15, 2023

Building an API Domain Model

In my last article, API Design First is not API Design First, I presented a vastly over-simplified introduction of a domain modeling process and its desired outcomes. Our goal is to build a shared understanding of the problem for our team, focusing on the domain’s ubiquitous language. In this next foray into the prerequisite for good API design process, we’re going to get down and dirty and apply some of this to our fictional software start up scenario to build a working domain model.

Published: February 21, 2023

Chain Links Domain Model

I present here a possible Domain Model for the Chain Links application that accompanies The Language of API Design series in API Design Matters. Below are several key elements of a Domain Model, with a brief description of each,

Published: March 7, 2023

From Domain Model to OpenAPI

We’ve built quite a bit of knowledge of the Chain Links API now: you know what the API needs to do, and what the resources are, and some of the constraints and bounds for the resources and behaviors. You can view my more complete Chain Links Domain Model below—this will be the foundation for the Chain Links API design.

Published: March 9, 2023

What Am I Getting Out of This?

In the last article of The Language of API Design series, you saw how to express a few HTTP API operations to list resources in the Chain Links domain model, focusing on the design for calling the getChainLinks operation. (If you are just jumping into API Design Matters, I recommend going back and skimming the previous articles in the The Language of API Design series to get caught up.)

Published: March 16, 2023

Your API Has Problems. Deal With It.

Learn how RESTful APIs can respond to run-time problems

Published: March 26, 2023

Don’t Repeat Yourself When Designing APIs

Techniques for keeping your OpenAPI definitions DRY

Published: April 9, 2023

Growing a Language

Today, we take a short diversion from our normal journey through The Language of API Design—though we’re not deviating very far off our path.

Published: April 18, 2023

Learning the Language of API Data

On the road to becoming fluent with JSON Schema

Published: May 18, 2023

Composing API Models with JSON Schema

Use JSON Schema effectively to build real API request and response bodies

Published: June 5, 2023

Master JSON Schema’s Subtleties

Don’t be Surprised by JSON Schema’s Surprising Surprises (Part I)

Published: July 11, 2023

Master More JSON Schema’s Subtleties

Don’t be Surprised by JSON Schema’s Surprising Surprises (Part II)

Published: July 30, 2023

Keep Me Updated, OK?

We’ve already explored API List operations in depth in What Am I Getting Out of This? We also covered how to Create new resources in Getting Creative with OpenAPI. Next, let’s explore the many API design matters of Updating resources.

Published: October 6, 2023

Understanding the Language of API Security

How OpenAPI expresses API security…. and how it does not

Published: November 6, 2023

We Talk “API” One Day

What we mean when we talk about APIs

Published: December 26, 2023

What is the Meaning of This?

Semantics is the key to successful API/AI integration

Published: January 11, 2024

Improve the Security of Your API’s Data

Employ the strength of JSON Schema in OpenAPI to increase your API’s security

Published: February 6, 2024

The API Design Mind Game

When it comes to API puzzles, it’s all in your head

Published: March 21, 2024

The Art of API Design

… and the science of API Design

Published: April 11, 2024

I See Patterns

Humans are great at recognizing patterns. In software, software design patterns gained popularity in the 1990’s as a way of capturing design constraints and reusable solutions to recurring problems, accompanied by a “pattern language” to describe them. (Fielding’s dissertation even cites Christopher Alexander’s thinking on pattern languages.)

Published: May 8, 2024