Below is the full archive of API Design Matters articles in chronological order. You can also visit articles tagged with specific topics:
To use the API Design Matters RSS feed, copy this URL:
https://apidesignmatters.org/feed.xml
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
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
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
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
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
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
A collection of memes that matter to API Design
Published: March 25, 2023
Learn how RESTful APIs can respond to run-time problems
Published: March 26, 2023
Techniques for keeping your OpenAPI definitions DRY
Published: April 9, 2023
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
On the road to becoming fluent with JSON Schema
Published: May 18, 2023
Use JSON Schema effectively to build real API request and response bodies
Published: June 5, 2023
Don’t be Surprised by JSON Schema’s Surprising Surprises (Part I)
Published: July 11, 2023
Don’t be Surprised by JSON Schema’s Surprising Surprises (Part II)
Published: July 30, 2023
Defining resource creation and update operations with OpenAPI
Published: August 27, 2023
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
How OpenAPI expresses API security…. and how it does not
Published: November 6, 2023
What we mean when we talk about APIs
Published: December 26, 2023
Semantics is the key to successful API/AI integration
Published: January 11, 2024
Employ the strength of JSON Schema in OpenAPI to increase your API’s security
Published: February 6, 2024
When it comes to API puzzles, it’s all in your head
Published: March 21, 2024
Why I don’t use Pet Store API in API Design Matters
Published: April 1, 2024
… and the science of API Design
Published: April 11, 2024
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
or, Being Resourceful in REStful API Design
Published: June 17, 2024
Patterns for naming things in APIs
Published: July 15, 2024
Techniques for API Request Validation
Published: August 19, 2024
Make API responses more self-descriptive with reference objects
Published: September 19, 2024
Hypermedia as the Engine of Application State
Published: January 23, 2025
Patterns for Web API Query Parameters
Published: March 16, 2025
200 is Not OK
Published: April 22, 2025
Pro tip: Do not let internal implementation constraints leak into your API
Published: June 3, 2025
Shane O’Conner (Founding Team @ Scalar ) has started a Q&A series on LinkedIn called Behind The API. Shane graciously asked me to participate, and also allowed me to re-publish the content here. Below is Shane’s initial announcement of the Q&A, followed by the full content.
Published: November 16, 2025
See how two famous laws interplay with API Design
As we journey down the path of API design and delivery, the topic of governance comes up often. There may be some resistance from multiple teams when it comes to governing APIs. Management may not like spending time and team capacity on governing the API program, fearing that this slows down time-to-market. Engineering teams may resist, feeling that it overly constrains them or limits their creativity.
Published: May 13, 2026
Join the discussion