Your Guide to The Language of API Design
An overview of the articles in The Language of APIs series
For new subscribers and visitors to API Design Matters, this guide will orient you to the The Language of APIs 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 (and the fictional example used throughout) of 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.
1. The Language of API Design
In the inaugural post in the series, I introduce the OpenAPI Specification as the prevalent language for describing REST APIs, and describe some of the benefits one gains by using a standard specification. I introduce the fictitious Chain Links fan fiction site and application and it’s API design task as a foundation for learning how to map application problems to API designs. Published 2023/02/08
2. API Design First is not API Design First
Language is key to communication and understanding on many levels. Although API Design First is all the rage, it is a misnomer: a more important phase precedes API Design. I give a gentle introduction to Domain Driven Design (DDD) and the Align, Design, Define, Refine approach to understanding requirements and solving business problems with APIs. I explain the concept of the Ubiquitous Language of DDD, go meta and define DDD’s own ubiquitous language, and establish the role that language and terminology has on API design. Published 2023/02/15
3. Building a Domain Model
In this article, we apply the principles of DDD and the reader (that’s you) and I together define the Ubiquitous Language of our fictional problem domain, the Chain Links API. We define the domain and context, the key resources in the Chain Links domain, and the key behaviors through the exposition of a more detailed user story and create a domain model document. Published 2023/02/21
4. From Domain Model to OpenAPI
Now that we have a more complete domain model for the Chain Links fan fiction application, I walk through the initial phases of mapping the model into an OpenAPI expression, by creating an OpenAPI document and defining API paths (or routes) for the primary resources in the domain. I also introduce the first set of API operations that satisfy some of the behavior requirements from the domain model, and discuss basic resource-oriented architecture and URL structures for API resources. Published 2023/03/09
5. What Am I Getting Out of This?
Whereas the previous article defined how a client can make an API request, few (if any) APIs are useful if they don’t return responses to those requests. In this article, we have the first of many discussions on mapping API constructs such as DDD’s value objects to JSON Schemas, another key language of API design. We then see how JSON Schemas are connected to the API operations described in OpenAPI. Published 2023/03/16
6. Your API Has Problems. Deal With It.
Going beyond the success response modeling introduced in What Am I Getting Out of This?, in this article you learn how to report problems encountered in an API by returning correct HTTP status codes, how to list the expected errors for operations in an OpenAPI document, and apply a standard JSON problem representation to the problem responses. Published 2023/03/26
7. "Don't Repeat Yourself" When Designing APIs
Your journey of implementing API ideas with OpenAPI designs has reached a critical mass. In previous articles, you’ve seen how to model responses for GET operations as well as describing problem and error responses. In both cases, we include the JSON Schema to describe the results directly in the operation’s responses object. However, this is not scalable, as it would require copious copying and pasting, which in turn leads to fragile code and increased likelihood of bugs. This article will show you the path of API Design enlightenment via OpenAPI’s support for the Don't Repeat Yourself Principle, otherwise known as the DRY principle. Published 2020-04-09
8. Growing a Language
In "Growing a Language", I reiterate the central theme of my Language Of API Design series: How the languages of API design express API design ideas, and how such languages (and our mastery of them) grow... inspired by a seminal talk that is 25 years old this year. Published 2023-04-18
9. Learning the Language of API Data
The OpenAPI Specification is a language for expressing the design of an API. But contained within OpenAPI is another language: JSON Schema. Like OpenAPI, JSON Schema is defined by a standards specification (published at json-schema.org). You saw the tip of the JSON Schema iceberg in What Am I Getting Out of This?, but that wee bit of knowledge will only get you so far. Diving into JSON Schema and gaining fluency will require several API Design Matters articles—there is much to learn! Published 2023-05-18
10. Composing API Models with JSON Schema
I expand upon API request and response data modeling with JSON Schema. We saw last time how constructing a deeply nested schema does not result in a good developer experience when generating a Software Development Kit (SDK) for our Chain Links API. We’ll learn how restructuring the models improves the generated SDKs and also allows us to keep our API definitions DRY. Published 2023-06-08
11. Master JSON Schema’s Subtleties
Before returning to API design with OpenAPI, I want to present a detailed post (well, two actually) on the more subtle nuances of JSON Schema as a language for designing the data of APIs. Knowing these details will help you understand other APIs’ schemas and help you construct your own. Published 2023-07-11
12. Master More JSON Schema's Subtleties
I present Part II of the Master JSON Schema's Subtleties article, imaginatively titled Master More JSON Schema’s Subtleties. I explore more use of unevaluatedProperties, JSON Merge Patch, why you should avoid format: uuid, discuss "null" as a type, and why you should always define a type constraint… except when you shouldn’t. Published 2023-07-30
13. Getting Creative with OpenAPI
Developers like to consider themselves as creators—we create code, we create ideas, we create experiences. In the realm of APIs, we create interfaces so others can use our software. An important aspect of most APIs is their ability to create things as well. In the past, we started at the end of the “CRUDL” initialism and discussed basic List operations in APIs. Next, we jump to the beginning of that “CRUDL” initialism and talk about the Create operations. Along the way, we’ll apply many of the skills we’ve covered in the previous dozen or so articles of the Language of API Design. Published 2023-08-27
14. Keep Me Updated, OK?
Let’s explore the many API design matters of Updating resources and the JSON Merge Patch standard. Published 2023-10-07
15: Understanding the Language of API Security
We begin a deeper dive into expressing API Security with OpenAPI, by exploring the notation of security schemes and security requirement objects, with some commentary on the tradeoffs between conciseness vs. consistency, and what can and cannot be expressed with OpenAPI when it comes to keeping your API secure. Published 2023-11-06
16: Improve the Security of Your API's Data
A follow up to Issue #15 in the series, this article explores how adding constraints to the JSON Schemas in an OpenAPI definition can boost the security of the API an protect against two common/well-known OWASP Top Ten API Security vulnerabilities.
Pet Store: Just Say No!
I want to completely divorce API Design Matters from the plague that is the “Pet Store” API. It is cliche, and it exhibits what I consider poor API design that should not be emulated. Accompanying The Language of API Design is a sample API called the “Chain Links API”. The API supports a hypothetical social media site, called “Chain Links”. This site allows fan fiction authors to collaborate on fiction stories, call chains, by adding new story elements (text, media, etc) called chain links. Fan fiction chains include characters that live in fictional universes.
More details of the Chain Links API domain are included below.