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.)

alt text

If you have been reading API Design Matters, you may have noticed a recurring theme1 : I’m a big advocate of patterns.

Welcome to the next article in The Language of API Design series. Rather than jumping into the middle of this series, I encourage new visitors start by reading The Language of API Design and scanning previous posts in the series.

I’m an advocate because I believe patterns are a great communication tool. (How’s that for getting controversial?) Seeing patterns—or having them pointed out in a software design—accelerates our understanding of larger systems. Patterns help us manage complexity by pushing mundane details down a level and allowing us to discuss software at a higher level of abstraction. (Humans are really good at abstraction, too.)

Omitted here out of respect for my readers: Cliche meme based on either “I see dead people” from The Sixth Sense, or “API Patterns… API Patterns Everywhere” from Toy Story.

Of course, the other main API Design Matters theme you may have noticed is that of languages, and specifically a language’s expressiveness — it’s ability to express and communicate ideas. Just as a for loop is easy to understand as a programming pattern or language idiom, a pattern language can define a vocabulary that conveys a huge amount of meaning with a small number of words. That’s powerful.

Patterns are a great communication tool

This API Design Matters series will focus on a number of API design patterns — recurring patterns that we see over and over in API designs.

Some of the API Design Patterns I’ll discuss:

  • Oh, CRUD (or, Being Resourceful)
  • Resources and Collections; pagination/filtering/sorting
  • URL patterns and meta-patterns
  • The Mother of All Initialism: HATEOAS and Hypermedia
  • REST is a State of Mind
  • Resource sets to model state changes on resources
  • Revisionist History: Pattern for immutable revisions of mutable resources

Oops, I did it again

Handling errors in APIs, error/problem responses, and common abstract resource representation.

Certainly, I’m not the first to write about API patterns. There are several excellent resources which discuss API patterns, notably:

API Design Patterns by J.J. Geewax

RESTful Web API Patterns and Practices Cookbook by Mike Amundsen

API Design Patterns for REST by Adam DuVander

Essential API Design Patterns: A Guide to Crafting Superior Web Services by Moesif

1 Kindly note that I did not say “recurring pattern” ;-)

Join the discussion

Note: This article was originally published on the auhor’s API Design Matters Substack.