See how two famous laws interplay with API Design

Note: Below is an article I originally wrote for Nordic APIs, published as Meet Hyrum and Postel on December 9, 2020. – djb, Nov 16, 2025

How do Hyrum’s Law and Postel’s Law affect API designs?

Luckily for us humans, and especially that narrow subclass of humans who build APIs, API design is a field that has not been automated or botified… yet. Sure, one can point at a database schema and generate what one can label an “Application Programming Interface.” But it is an API only in a literal sense — and certainly not in a RESTful one. It does not provide any of the benefits of designing an API abstraction layer, such as decoupling your API from the back end. (See Nordic APIs’ How To Build And Enforce Great API Governance.)

One of the reasons API design is more an art than a science is that human intelligence is still required to weigh the competing forces that arise. There are numerous API design cookbooks available, such as REST API cookbook, The Design of Web APIs (new second edition). RESTful Web APIs, and Design and Build Great Web APIs. These resources offer several categories and layers of design guidelines that are easy for humans to understand and apply… less so for an artificial intelligence. The art of API design lies in weighing and making decisions around those tradeoffs.

Consider two human-centric software design principles which are so impactful they are better characterized as laws:

[John] Postel’s Law

TCP implementations should follow a general principle of robustness: be conservative in what you do, be liberal in what you accept from others.

Postel’s Law is so darn useful that it has been generalized away from the narrow realm of TCP implementations as the Robustness Principle:

Be conservative in what you send, be liberal in what you accept.

Postel’s Law focuses on making service implementations more robust by allowing for interfaces and messages to evolve over time. A nice consequence of Postel’s Law is that it can make APIs easier to use, which we’ll see in a moment.

Hyrum [Wright]’s Law

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.

While Postel’s Law is one of those guardrails that help you design robust APIs, Hyrum’s Law, coined by Hyrum Wright, is one of those 1,000-foot cliff drop-offs along that narrow, winding, gravel mountain road. You know, the one without the guardrail. Hyrum’s Law is so treacherous; it even has an XKCD manifestation.

The problem that our human brains can solve but the robot overlords can’t (yet) is how to weigh Postel against Hyrum. You probably want something a little more concrete (unless you’ve already driven over that cliff, in which case you want something a little more silk-like \ux1fa82;).

Let’s look at some examples.

Examples of Postel’s Law in Action

Example 1: Imagine you have been tasked to build an API for authors to submit content for publication on Nordic APIs’ site. One API operation in your “Submissions API” accepts the author’s contact phone number. With Postel’s Law in mind, you design the API to accept multiple formats, such as "(910) 555-1234" or "910.555.1234" or "9105551234". You also design the API to always return E.164 formatted phone numbers such as "+19105551234". This interpretation of “Be conservative in what you send, be liberal in what you accept” yields an API that is easier for clients to use:

Clients can pass phone numbers in multiple formats according to user input preferences; each client does not have to normalize phone numbers. API consumers do not have to worry about parsing/supporting various phone number formats returned in the API’s responses, only one well-defined format.

Example 2: The Submissions API operation to search submissions has a query parameter, defined by the OpenAPI Specification (OAS) notation:

parameters:
  - name: published
    in: query
    type: boolean

The OAS relies on JSON Schema (see 7 API Standards Bodies To Get Involved With) to define the types of properties, parameters, and request bodies. So, clearly, one can pass ...?published=true or ...?published=false. However, some client languages don’t use true and false tokens for Boolean values. Python, for example, uses True and False instead.

Should one apply Postel’s Law and be liberal in what the API accepts here, as with the phone numbers? It may be tempting to code the API to accept ?published=True, ?published=TRUE, ?published=t, or even ?published=yes and ?published=1. All are possible representations of a “true” value in various client programming languages. Your implementation framework may even have a nice utility that can convert all kinds of values into Boolean values. However, this example and the next show the risks of adding too much flexibility in input validation.

Example 3: Your API has an operation that accepts a request body schema with a property, publicationDate. Thus, a valid JSON request would specify the date as follows:

{ ..., "publicationDate": "2020-12-09", ... }

Let’s say you are on a Postel’s Law roll and code the implementation to accept other date formats, such as "2020/12/09" or "Dec 09, 2020" for the date December 9, 2020, to make the API easier to use (ignoring the fact that "12/09/2020" is ambiguous). Knowing it is critical to validate all user input in a pubic API, you find a nice open-source library that parses dates. But a year later, the team migrates the API implementation to a new language runtime and, as mart of the migration, chooses to adopt a new library that also accepts these formats. Such backend changes should not affect API consumers. Unbeknownst to you, some clients have been passing dates in "09-Dec-2020" format, which the old library supported. The new framework and library don’t handle this, nor does it support all the “truthy” values you previously allowed for the ?published= query parameter. Hyrum’s Law has struck!

API Evolution

The original intent of Postel’s Law was to account for evolution of the interface. (See also Nordic APIs’ What’s The Difference Between Versioning and Revisioning APIs?.) Examples of evolution in the API space include adding new properties to a JSON schema. This is a core principle of “good” REST APIs: the service and clients should be free to evolve (in a compatible manner) independently of each other. For example, the first release of the publishing API may allow passing only the title and publication date properties:

{ "title": "Meet Hyrum and Postel",
  "publicationDate": "2020-12-09"
}

A new release of the service may add a new revision property, so requests may look like:

{ "title": "Meet Hyrum and Postel",
  "publicationDate": "2020-12-09" }
  "revision": "2020-10-28"
}

A robust service would allow this request (even in the first release!) by ignoring (and perhaps logging) properties that it does not recognize, rather than treating them as an error. Clients who consume such responses should also be lenient in what they receive. A client built for the first release of an API should not fail if it connects to the newer release of the API that includes new properties.

One consequence of API design that Postel’s Law tells us:

When defining JSON Schemas for our APIs, avoid using additionalProperties: false. Doing so slams the door in John Postel’s face!

Hyrum’s Law states that all observable behaviors of your system will be depended on by somebody. This includes behaviors that are not explicitly accounted for in the API design or documentation, such as the “09-Dec-2020” date format above. If one considers an API definition to be a software contract, then Hyrum’s Law means consumers have found (and depend on) loopholes in that contract. Industry veterans are all familiar with a customer who has come to rely on buggy behavior, which they quickly learn about only after releasing a bug patch!

Hyrum’s Law and API Evolution

APIs must evolve over time. Hyrum’s Law tells us that such change will be painful. Imagine you did not provide an OpenAPI definition with your first Submission API releases, but you chose to add it after several requests from consumers. You describe the publicationDate string property and its need to represent a date value:

publicationDate:
  description: The intended publication date of the submission.
  type: string
  format: date
  example: "2020-12-09"

Hyrum’s Law also means pain here. An API design that adheres strictly to the OpenAPI Specification and JSON Schema validation does not always allow for the “be liberal in what you accept” clause of Postel’s Law.

JSON Schema tells us that a string with the date format must follow the RFC 3339 “MMMM-DD-YY” format. API frameworks and libraries based on OAS and JSON Schema may not allow input that does not pass strict JSON Schema validation.

In effect, this design choice imposes a stricter constraint on the API. Other formats that users have come to depend on are not allowed. To maintain compatibility, you are forced to abandon the use of format: date for the property to maintain your kinship with Postel’s Law. (With luck, you find out before you publish the OAS API definition.) But to guard against Hyrum’s Law, you need to specify all the allowed date formats.

Another example of Hyrum’s Law wreaking havoc would be a client that passes:

{ "title": "NordicAPIs",
  "publicationDate": "2020-12-09",
  "revision": 25 }

to the above publishing example. Perhaps because they are reusing a response from another API that includes a revision, and they simply don’t remove it before calling your Submissions API. This behavior was allowed in the first release, and perhaps the client even comes to depend on this behavior. However, once the service adds a revision property with type: string (or any non-numeric type), that client request will cause an error in the Sumissions API. Something as simple as adding a new property can break existing consumers!

Unfortunately, there are many such ways that API evolution can have such ill effects: adding a value to an enum list or changing the maxLength of a string from 80 to 100 may break a consumer. Even changing the HTTP response code for an erroneous call from 400 to a more specific 422 will change an “observable behavior.”

I highly recommend Gareth Jones talk, Your API Spec Isn’t Worth the Paper It’s Written On](https://nordicapis.com/sessions/your-api-spec-isnt-worth-the-paper-its-written-on/), presented at Nordic API Austin Summit 2019. Gareth points out many ways that even small changes in APIs or their implementations can break clients.

Balancing Postel and Hyrum in Practice

The main impacts of Postel’s and Hyrum’s laws arise: To prevent unintentional dependencies on unspecified data and behavior, the API definition would need to do the following:

1. Enumerate all the variations on how developers will use it, such as listing all allowed formats of all input and all possible API call sequences. The goal is to turn the API software contract into an “iron-clad contract” and remove all loopholes.
2. Disallow any input that deviates from the new, strict API definition — even “harmless” ones. This must start with the first release by explicitly failing operations and data outside the API contract. Thus, no client can come to depend on those behaviors. Clearly, with any non-trivial API, it is impossible to do either! Even listing only common variations can add significant bloat to the API definition. Unfortunately, larger, more verbose API definitions are harder to use compared to concise API definitions. They also add significant cost to the implementation, including developing exhaustive, comprehensive regression tests. Avoiding the cliff of Hyrum’s law is at odds with Postel’s Law of being liberal in what you accept. Trying to follow both means giving up easy to understand, concise APIs, or it locks you into a backend that cannot evolve.

The ultimate artful engineering solution is to be aware of both laws and weigh them in each API design decision. One tactic is to set reasonable expectations with your consumers about API evolution and change. Don’t be an automaton when it comes to API design. Instead, use your experience and intelligence to design APIs that respect the boundaries laid down by Hyrum and Postel and which can evolve as your API consumers’ needs change.

Join the discussion

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

Introduction

Below is Shane’s first LinkedIn announcement on Nov 11, 2025, sharing the Behind The API featuring David Biesack article:

I’ve been thinking a lot about what “mature API strategy” actually means as we build Scalar. So I did what any sane person would do: tracked down someone with “Chief API Officer” in their title and asked him everything.

David Biesack spent some time walking me through the reality of API programs - not just the highlights, but the actual messy, cultural, people-first work.

A few things that come up;

The “API-first” paradox: APIs can’t come first. The business problem does. But once you solve that, APIs become the unified way you deliver your entire business value. That mindset shift changes everything.

Governance = velocity: I’ve always known this, but hearing David explain how standards like OAuth2 and OpenID Connect are precisely what enable speed (not constrain it) reframed the whole governance conversation for me.

The people problem: API maturity isn’t a tech problem. It’s culture. It’s convincing people that “API as a Product” means something fundamentally different than “we have APIs.”

If you’re working in APIs, developer tools, or platform strategy—I think you’ll find something useful here.

Enjoy!

* if you’d like to partake in my interview series, please let me know. Would love to chat with as many of you as possible.

#BehindTheAPI

(Image by Shane O’Conner, used with permision)

The remainder of this API Design Matters article is a full reprint of Shane’s full Behind The API article, courtesy of Shane (Thanks, Shane!):

Behind the API with David Biesack

An interview with David Biesack, who is Chief API Officer at Apiture (now part of CSI).

* all views expressed are his own and are not of his employer

Shane: Most people don’t wake up dreaming of being a ‘Chief API Officer.’ Walk me through how this role came to be at Apiture - was it reactive to chaos or proactive vision?

David: This was a proactive move that I suggested to Apiture executives as the API program matured and began to realize its potential and impact. “API” was in the founding DNA of the company, so it was not a hard sell that APIs merited guidance and governance and quality controls—and ultimately responsibility. We could establish the role, or it we could partition it out and dilute it amongst other roles, to the risk and detriment of all. So yes, proactive against chaos.

Shane: You lead Apiture’s ‘API First’ initiative. For folks who think that just means ‘we have APIs’- what does TRUE API-first actually look like in practice? What are the non-negotiables?

David: APIs exist within a business context, so APIs can’t come first — the problems and needs of the user and the business capabilities come first. APIs are just part of a technical solution to the business problems, so APIs come after fully understanding the business domain and its problems. They are the vehicle for accessing the core capabilities, so they must be shaped based on how users want to consume those capabilities. If the API came first, it would not align with the desired outcomes. So, the non-negotiable is accepting that APIs are part of a larger ecosystem. People who work on APIs must rely on others—the domain experts, the customers, product managers and business analysts and strategists—to tell them what needs to be solved before taking any “how” first steps with building an API Secondly, a true API First mindset means the API solution is the primary tool in the business’ toolbelt for gaining access to the domain. Rather than implementing five competing access methods (and differing authorization management, etc) to your business capabilities, focus on APIs as the first and foremost way of exposing those features to all consumers, internal and external. This unifying theme brings tremendous power, more secure solutions, and faster business agility.”

Shane: What’s the hardest part about instilling an API-first mindset in an organization? Is it technical, cultural, or something else entirely?

David: It is definitely culture — one can’t instill a mindset with technology (I’m not gonna let anyone put a chip in my brain). Many people talk about “API as a Product”, and I think grasping that idea is the largest hurdle: One of the hardest things to understand is that providing a unified way for others to access your business’ data and processes requires a newer, deeper way of thinking what your product is. It forces people to think what is the true value of your business, and realizing that it does not have to be packaged up in some older, rigid, legacy, monetized widget, but that by enabling your capabilities through APIs, you can really understand the value your company provides, then make it available to more partners and markets. For many, holding onto a UX-first mindset (and the business analysis tools that lock them into that mindset) is what holds them back. I get it — comfort, momentum, familiarity are hard things to let go. But when they shift to an API-first mindset, it clicks and it becomes very freeing and powerful for all parties, and this leads to accelerated success.”

Shane: Let’s talk API governance - it’s one of those things everyone nods about but few do well. How do you think about the balance between enabling developer velocity and maintaining standards?

David: This one is relatively easy to position, because standards are precisely what enable productivity and deliver velocity. Imagine how slow you would be if you also had to take time to invent, implement, and harden a new authorization protocol instead of relying on standards such as OpenID Connect and OAuth 2? Reality Check: no existing libraries, frameworks, tools, agents or infrastructure would integrate with your non-standard API. Who would consume your API if it were not built upon the standards that all developers know and expect API Governance is all about managing risk—reducing risk and enabling velocity by following standards, so teams can focus on getting their unique capabilities right, rather than re-implementing the API “chrome” of HTTP or JSON or OAuth2 or encryption or inventing a new protocol that no one else understands. The other dimension of your question is balancing developer creativity vs. following standards. I spoke about this at my talk at the Nordic APIs Austin API Summit in 2024.

Shane: You talk about ‘APIs as a Product’ - what does that mindset shift mean in practical terms? How does it change how you build, document, and support APIs?

David: I hinted at this above… There is a spectrum of engagement in APIs as a Product. The most trivial (and least useful) is the “widget” approach to commoditizing and commercializing digital products, as done with any product. The other extreme is full buy-in throughout the organization to “API all the things”, to rephrase your main business value as digital capabilities that are available via APIs and which allow innovation and growth by inviting other organizations to partner with you. This is a monumental shift, because it requires a significant investment in doing it right — getting security right, getting consistency and evolution right, aligning teams on a strategic vision, addressing Developer Experience. For the business, seeing APIs as part of the innovation chain, as part of what brings your business’ value to customers, shifts it from being an expense sink to a growth product.

Shane: Developer Experience is core to your role. What are the most common DX sins you see API teams commit? And what separates a ‘good enough’ API from a genuinely great one?

David: I think the most common mistake is for engineers to not think like their API consumers. This applies to so many aspects, from using internal jargon, to making unstated assumptions about intimate internal knowledge about how things work, to missing the core abstractions and concepts that consumers think about… or simply not answering (in the API design, or in the accompanying documentation) the important questions that developers needs to know about your API. My goal is to make APIs a joy to work with. If you have ever worked with a library that “thought” the way you did and which made it a breeze to use, vs. a highly opinionated competing library that incurred mental load that was all friction and confusion, then you know joy vs. agony. “Good enough” is an API that allows solving the obvious problems, whereas a Great API and corresponding developer experience are truly expressive, adaptable, intuitive, flexible, simple, composable, and comprehensible, yet highly usable. They allow solving the 20% obvious use cases as well as the 80% harder use cases. Of course, the risk is making the API too general, too complex, too abstract, so it does everything poorly but does nothing well. Never trade simplicity and directness for overly abstracted “elegance”. Ever try to program an actual Turing Machine? Sure, it can perform any computation, but at what cost to Developer Experience? DX means delivering the right abstractions based on the API consumer’s conceptual model, not an API coupled to some elegant platform design that they don’t care about.”

Shane: When you think about your external developer partners using Apiture’s open banking APIs, what metrics or signals tell you the developer experience is working?

David: We have the great fortune of working with a world-class Support team and an equally stellar Customer Success team, so we get great (and fast) feedback from partners through them. Our company mantra has always been to “Treat every customer like they were your only customer”, so that leads directly into seeking and accepting great feedback. We hear it when someone can’t achieve their goals, and also when they do succeed

Shane: What’s your philosophy on API versioning and evolution when you have that many partners depending on your APIs? How do you ship new capabilities without breaking things?

David: Joshua Bloch wrote, “Public APIs, like diamonds, are forever.” I once gave a talk on API evolution and backwards compatibility at SAS, where I took a SAS program from the 1976 SAS Manual and ran it on the most recent version of SAS — and it worked, unchanged, 40+ year later. That’s my goal with APIs— design for evolution by building in enough extensibility to allow for the system to change. We’ve done a great job of this, by understanding and anticipating how a system can or will change, and guiding partners along the way. We’re lucky enough to be able to build and validate our APIs alongside our front-end mobile and web and system applications, to get early enough feedback. But just as I mentioned the API First myth above, we also push back heavily on the product team to get firm commitments about what can change in the future. For example, cardinality is always a critical aspect of API design, so whenever we get a requirement for one of this, or two of that, we always push back and design things with arrays to allow future evolution, or use arrays of objects rather than arrays of strings, to allow the data to evolve in multiple dimensions.

Shane: CSI just acquired Apiture, and the press release specifically called out your ‘API-first platform’ and ‘API-driven flexibility’ as key value drivers. That’s not typical M&A language. What do you think that signals about where API strategy fits in the broader fintech landscape?

David: I’m heartened to hear this, certainly. I hope this bodes well for the broader industry. There is certainly a lot of activity and change in the industry, but APIs are here to stay, especially with the growth of AI agents. By being thoughtful and by recognizing the growth enabled by partnerships built on APIs, others will also position APIs as an crucial dimension of their portfolio. And investment firms etc. will be looking at API enablement and robust API governance and developer experience as hallmarks of mature, valuable companies.

Shane: Who are some other API leaders or companies doing interesting work in this space that you admire or learn from?

David: Top of mind is Matthew Reinbold. I appreciate his thoughtful analysis and consistent reminder that most of our industry problems (especially those around API Governance) are people problems, not technology problems. We also learn from the past, and his work on software forensics is so valuable and intriguing

I’ll attend a keynote or talk by Mike Amundsen any chance I get.

I also admire Kin Lane , of course, as he has established a long record of telling stories about API success and for building and inspiring our community around the people behind the APIs.”

Shane: Last one - if someone’s reading this and thinking about how to mature their own API program, what’s your advice on where to start?

David: There is no reason to jump into this alone. I feel lucky to be involved with such a great community of passionate people who want to help each other. When you can, attend conferences and make yourself known. Don’t be shy, because everyone is helpful and wants to see their peers succeed. Participate to the extent you can — even sign up to present at an API conference

One of my favorite quotes, attributable to Richard Feynman: “If you want to master something, teach it!”.

I hope you enjoyed the article. Thank you again Shane for this and other #BehindTheAPI content. I hope all my readers will check it out - there’s lots of great content there — please read!

Join the discussion

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

Origins of API Design Matters

I started API Design Matters in early 2023 (if you’ve been reading since then, Thank You!), but the idea goes back much further.

Back in the mid 90’s (yeah, I’ve been around a while…) I was deep into that new “Java thang”. In June 2025, Emmanuel Paraskakis shared slides from a 2007 talk Joshua Bloch had given, titled How to Design Good APIs, and Why it Matters. I had seen a version of this talk in my Java years at a conference, and I had the pleasure of working with Java API design experts like Josh Bloch and Doug Lea as they built out the Collection framework (lists, maps, etc) for Java 2 in the early days. The title of that talk lodged itself in the back of my brain, almost as much as the content of the talk, and both were a large part of why I created API Design Matters… and why I named it as I did.

Josh and Doug and others were gracious and accepted a lot of input from the younger me, and answered my questions about the emerging design of Java’s Collection framework. Those conversations are lost to time, but I do remember their impact. A specific example I recall from the early Java Collection API design discussions centered on the collection interfaces’ isEmpty() query function, which returns true if the collection was empty (had no items), false if not. I asked about the need for such a function, since the collections already had a length() function. It seemed unnecessary to add a collection.isEmpty() method because a client could trivially use (collection.length() == 0). However, Josh kindly pointed out that, with so many different/possible collection implementations, the length() function may be expensive to compute. For example, for a linked list, computing linkedList.length() is O(n) (where n is the number of items in the list), not O(1), whereas the implementation of linkedList.isEmpty() function for a linked list is trivially O(1). While API composability is nice, it may come at the cost of performance.

Many of the practices and pragmas Josh shared then, as well in his InfoQ article, “Bumper-Sticker API Design”, stuck with me because they also apply to Web API design.

The one principle I have shared the most:

Public APIs, like diamonds, are forever.”

— Joshua Bloch

When I worked at SAS, I shared an example of this principle several times when discussing API design. As late as 2017, I would show examples of small SAS programs from the 1976 SAS manual, and the programs continued to work unaltered in the SAS System of 2017. Backwards compatibility is as critical to the longevity of an API as it is to a programming language/platform.

Josh also wrote:

If there is a fundamental theorem of API design, this is it … Every facet of an API should be as small as possible, but no smaller. You can always add things later, but you can’t take them away. Minimizing conceptual weight is more important than class- or method-count.

Obviously, design forces often oppose on another. The collection interface footprint would be smaller without an isEmpty() function, but the negative impact of omitting it is offset by the benefit of including it.

Another important aspect of API Design Matters provenance that I wish to share is that none of the text in API Design Matters was generated by AI. (I did try AI for one image and I doubt I’ll do that again because the result was so awful). But I have never used an AI to draft, write, or rewrite my posts—It’s all me. It always will be.

I wish to acknowledge and thank Josh Bloch and Doug Lea and others who taught me so much.

Who has inspired your work with APIs? Let me know in the comments.

Join the discussion

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

Pro tip: Do not let internal implementation constraints leak into your API

In this edition of API Design Matters, I will discuss an API design practice that I recommend avoiding — leaking internal implementation details into the API design. This does not fit the original definition of an antipattern¹ but I’m going to use that term anyway and call Leaky Abstractions an API Design Antipattern.

Welcome to the next article in API Design Patterns series.

Exposing internal implementation details in an API design has negative consequences:

1. If the API design is too coupled to the underlying system, changes to that internal system likely will require changes to the API, which in turn can disrupt the API’s clients and consumers.
2. Such detail often reflects cultural, historical, technical and other influences that pertain to the engineering team, requirements, system and other constraints for a different scenario or problem set than the API. As such, the internal implementation decisions may not address the needs of the API. For example, databases are often designed to optimize for certain access patterns of the system or application they were originally built to support. Such patterns may be very different for an API that is designed to use that data at a later time.
3. Internal system design often uses jargon or concepts that are unrelated to the conceptual model that your API consumers have of your system. This impedes adoption of your API.

Thus, one should avoid letting the internal system design leak into the API in order to create and maintain an API abstraction that fits the API consumer’s needs. Don’t sacrifice API usability just to facilitate expediency in the API implementation.

(Corollary: avoid generating an API directly from a database schema.)

Here is a more concrete example. I recently saw the following construct in a third party API (I renamed the schema to keep the vendor anonymous, but I did not change the enum names.)

...
components:
  schemas:
    CommunicationMethod:
      title: Communication Method
      enum:
        - FAXI
        - EDIC
        - URID
        - EMAL
        - POST
        - SMSM
      type: string

Unfortunately, the schema that defines these enum values does not define what these values mean… this is understandable, since OpenAPI and JSON Schema do not provide a specific notation for describing what each enumeration in an enum list means. Still, a better developer experience calls for a description that tells the reader what each of these values means.

In this case, the descriptions of these values appear elsewhere in the OpenAPI source file, in the description of a property that is constrained by the schema. If this schema is needed elsewhere, it is likely the API author would either not describe the values at all or, more likely, follow the existing code pattern and duplicate this verbose description. The result would be fragile — if the API needed a new value in the list, this would require updating multiple descriptions in the API definition. This violates the Don’t Repeat Yourself (DRY) Principle, which I’ve discussed before:

Don’t Repeat Yourself When Designing APIs)

However, this WET (“Write Everything Twice”) design is not the real API design antipattern I want to discuss. Instead, it is the names of these enumerated strings that strike me as a leaky abstraction. Here is the definition of the property which uses this schema:

  properties:
        method:
          $ref: '#/components/schemas/CommunicationMethod'
          description: >-
            The method used to deliver the the status to the originator.
            - `EMAL` - Email
            - `URID` - URI (HTTP URL or similar)
            - `POST` - Postal services
            - `SMSM` - Short Message Service (SMS)
            - `FAXI` - FAX
            - `EDIC` - Electronic Data Interchange

Unfortunately, this API appears to leak some internal implementation constraints — perhaps this format is required by a separate pre-existing back end service, or some internal communication protocol, or perhaps even a database table where only 4 characters are allowed and EMAIL would not fit. However, there is no need to let such internal constraints affect the API design by constraining these enum strings to four characters with reduced readability and diminished self description.

The purpose of an API is to provide an abstraction of the underlying service. That abstraction should be expressed in terms the API consumer can use and understand, not just what is convenient for the implementor. The goals of the API designer—and implementor—should be to do the hard work to make the API easier to learn and use.

The goals of the API designer—and implementor—should be to do the hard work to make the API easier to learn and use.

The above example highlights several issues which decrease the API usability. For example:

I believe EMAIL would be much better than EMAL. Why decrease readability and increase cognitive load by removing just one letter? The abbreviated spelling reduces one’s ability to discuss (talk about) the API - i.e. one cannot simply mention EMAIL in a conversation and have it be easily understood - one might even have to spell it out E-M-A-L to avoid miscommunication.

Why add an I to "FAX", or add C to "EDI" (Electronic Data Interchange) or add an M to "SMS" Short Message Service (SMS) or add a D to "URI" — just to make them all 4 character strings? The terms FAX, EDI, SMS and URI are well-known, recognizable names; adding extra characters to them only obfuscates them, especially when the given definitions do not explain why those extra characters are there:

• SMSM - Short Message Service (SMS)
• FAXI - FAX
• EDIC - Electronic Data Interchange
• URID - URI (HTTP URL or similar)

I don’t know the origin of these names, but I suspect they came directly from implementation code. However, this semantic gap between the names and what they represent only increases API friction. There is no justification given here for why these enum values are named as they are (perhaps because there is no good rationale). The API design only makes consumers pause and ask “Why?”. When this happens, the API design detracts from the API’s purpose and becomes a pointless distraction.

Your API design should anticipate and answer the domain questions your consumers may have; it should not raise additional questions in their minds; nor should reading or using the API be frustrating. In other words:

APIs should help you solve your problems. APIs should not be your problem.

-The API Team Mantra:

A useful tip is to always look at your API design from the perspective of someone who has never seen your system before and does not have the same institutional knowledge that your API team has.

¹ Martin Fowler defines antipattern as “something that seems like a good idea when you begin, but leads you into trouble. Since then the term has often been used just to indicate any bad idea, but I think the original focus is more useful.” I’m using the latter interpretation of the term.

Join the discussion

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

200 is Not OK

In April 2025, I posted on LinkedIn:

The mantra of a good API Program Manager/Product Manager/Developer Advocate:

APIs should help you solve your problems. APIs should not be your problem.

— David Biesack

Today, I want to break this down and discuss API Success.

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.

As I’ve stated multiple times in podcasts where I’ve been a guest, the most important measure for API success is if it is solves real problems — if developers can use your API to build their applications. This means the API must be fit for purpose. I won’t be successful sending a text message to someone if I try to use the Amazon Web Services S3 cloud storage API, and I will find the Tenth Level of Hell if I try to upload a PDF of a Platinum Checking Account Terms and Conditions document, March 2025 revision, using the Twillio API.

Of course, to obtain this highest level of success, someone has to be able to find (i.e. discover) your API. This normally means being able to find it in an API registry (alas, ProgrammableWeb.com is no more), or find it through a search service (Google, Bing, Ask Jeeves!, pick your poison), as long as the API is on a web site that can be indexed by search services. (Pro tip - don’t put your API documentation behind a paywall or require registering and logging in to see the API documentation.) You may even try the AI chatbot of your choice to find the API that solves your problem, but for that to work, the AI engine needs to be able to see the API doc too… that’s not likely if the API doc is not easily available.

Either way, success in finding the right API requires that 1) the API be discoverable, and that 2) the API documentation clearly describes what the API does using the terms the potential consumer understands. I’ve seen way too many APIs described with woefully inadequate documentation. This often stems from technical people documenting the API “from the inside out” - i.e. describing how the system behind the API was designed (at one point in time…), or using internal code names or marketing terms, rather than documenting the API from the perspective of a consumer who, at least initially, knows next to nothing about your API.

This problem often extends deeply into the API documentation. There are few things worse than wasting bits and bytes (and your readers’ time) by providing a circular description of a field or operation that has an obscure or non-obvious purpose, described with undefined, obsolete, or misleading terms that raise more questions than answers:

  paths:
    /lincoln/v14/indications/:
      post:
         summary:
           Create a new laminar indication in the layers V12 API.

Don’t. Do. This.

(Yes, this is an excerpt from a vendor’s production API.)

A successful API clearly articulates its purpose, and the API design and documentation is built upon a foundation of a good conceptual model of the API’s domain. Such APIs arise when the team applies an API design process [ADDR recommended] rather than simply generating an API from a (soon to be obsolete) database schema or other structure which has been optimized for completely different use case than a clean API. (For my thoughts on using Generative AI to design APIs, see my The Art of API Design talk at Nordic APIs Austin API Summit, 2024)

A successful API designed via a solid process is more likely to provide the needed services.

Other problems you may encounter which inhibit API success are listed below. (Fret not, I’ve included lots of guidance on how to avoid the problems.)

1. An API that uses proprietary authorization. I led a Birds of a Feather session at an API conference a few years ago, and the largest hurdle that most of the participants expressed was getting API authentication/authorization right. It’s not too hard to use OpenIDConnect / OAuth2 correctly, especially if you use a good library that implements the protocol, but if an API has proprietary auth, then auth becomes a problem for your API users, an thus, your API becomes a problem for them.
2. An API that shuns HTTP standards.
3. The most common “hall of shame” for APIs (as I shared in My Favorite API Memes ) is not using correct 4XX and 5XX HTTP response codes and their semantics, but instead returning a 200 OK HTTP response code with { "error": true, ... } or { "success": false, ... }
4. A related problem is not using the correct 2xx response codes. If your POST creates a new resource, return 201, not 204. If your operation only has side effects but does not return any data, use a 204, not a 200.
5. Other examples are violating the uniform interface constraint of RESTful APIs - i.e. misusing the HTTP methods GET, PUT, POST, PATCH, DELETE; or a GET operation not being idempotent and safe (I once saw an API which used a GET operation to shut down a server! Do. Not. Do. This. _Run, don’t walk, away from such APIs.`) There was a lot of thought put into the design of the HTTP protocol, and the protocol ecosystem (libraries, proxies, gateways, and other intermediaries, etc), works well only if the protocol is followed. Ignorance or hubris says “I know better….”.
6. Not using the standard HTTP headers can be a problem. When a POST operation creates a new resource, return the new resource’s URL in the standard Location response header. If a resource is not ready, the GET operation should return the standard HTTP Retry-After response header.
7. Always use date-time values in RFC 3339 date-time format in UTC (“Zulu”) time done. Let clients map these to the user’s time zone or date/time format. The 5 laws of API dates and times by Jason Harmon is an oldie but a goodie…
8. An API that tries to avoid or minimize good use of JSON Schema is a problem. If you are defining an API, you owe it to your consumers to use JSON Schema well. This includes well-named schemas and properties, but also appropriate use of JSON Schema constraints and annotations as declarations of what data is valid in a request, and what data to expect in responses. The simplest example of such a problem is using strings with "Y" or "N" (or other string values) instead of boolean values, but it also includes exposing data taken directly from packed/encoded raw database fields, such as CHAR(1) codes or integer codes instead of self-describing enum values (See Amundsen’s Maxim). Here are a couple examples from a real-world API:
   
9. I don’t know about you, but I have no way to know how to use those single character code in the matches property… and the pattern: \w{1} constraint is certainly more obtuse than minLength: 1, maxLength: 1. A good API team will anticipate and answer the questions developers will have about your API. This is another reason to use the ADDR Process — and not skip the Refine phase, where you improve the API after feedback from real users.

   Don’t be afraid to refine and revise your API - instead, plan for it!

   — David Biesack

10. Any design aspect which violates basic and widely adopted conventions or developer expectations for how APIs work is a problem. Just as a good User Experience (UX) should be intentionally designed, a good Developer Experience (DX) should be intentionally designed,, with the goal of enabling the desired feature as intuitively as possible, without surprises.
11. An incomplete API is one example of violating these expectations. Normally, if your API supports creating a resource, it should also provide a way to update/patch that resource, fetch the most recent representation of that resource, and ultimately delete it. Omitting one or more leads to a frustratingly incomplete API that violates basic expectations.
12. Inconsistency can be is another caustic API problem. A consistent API design is easier to learn and use because it adheres to those expectations; an inconsistent design adds frustration. (Recommended: The 5 dimensions of API consistency by Arnaud Lauret)
13. An API that is not designed for evolution will not evolve gracefully when it needs to change… that’s a problem. An no, changing the API URL from /v1/... to /v2/... is not graceful API evolution.
14. An API that is not designed with error handling from the start will have problems when consumers start using the API — developers make mistakes; apps have bugs, and not every request is perfect. Oh, and hackers or bad actors will use invalid requests to launch Denial of Service Attacks or worse. (Pro Tip: use application/problem+json to describe the problems you detect)

15. A poor or fragmentary Developer Experience can add to the growing list of API problems:

    1. Onerous registration process
    2. Unclear license and terms of use
    3. Unclear or unpredictable rate plans
    4. Hard to navigate documentation; documentation that one can’t bookmark or reference or search… Oh, the plethora of potential API documentation problems!
    5. No easily downloaded OpenAPI documents, or OpenAPI documents based on OpenAPI 2.0 instead of 3.x, or “Swagger” documents (Again, see those favorite API memes !)

API success is certainly more than a lack of problems. Identifying and removing problems is a necessary but insufficient element of building a successful API or API program. “Zero problems” is analogous to the definition of the HTTP 200 status code…. you go to all the bother of assembling a API request, getting the authorization correct, pushing your API call over the wire, capturing the response… and you end up with the less-than-satisfactory

200 OK

It’s almost a let down! “Meh, your API call was, well, just OK.”

Instead, I prefer: “200 is Not (just) OK. It’s Success! Hooray! Hooray!”

By reducing the common problems and pitfalls when designing and delivering APIs, you can help your consumers insucceed… If you do it really well and focus not only on removing problems and roadblocks to success, but focus on enabling innovative solutions, you APIs may even be a joy to work with. You have my permission to be more than just OK; you may use “200 Success! Happy Happy Joy Joy!” in your API documentation.

Join the discussion

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

Patterns for Web API Query Parameters

There are many different patterns for using query parameters in web APIs. Today’s article in my API Design Patterns series in API Design Matters is about query parameters in Web APIs. Let’s explore some of these 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.

It is what it is

In HTTP APIS, query parameters occur after the path and before optional anchor tags in a URL. The query parameters begin with the ? special character, which is followed by a &-delimited list of name=value pairs

It’s quite natural to interpret this = character to mean equality, i.e ?x=6 means “where x equals 6”. However, I prefer to interpret this = character as “is” , such as “where x is 6”

Thus, one can read or “interpret” a URL such as the following (ignore line breaks)

http://api.chainlinks.example.com/universes
?author=au345bd84
&genre=fantasy

as

universes where
the author is (the author with id au345bd84)
and genre is “fantasy”

I find this style slightly more literate as well as more flexible than a rigid “equals” interpretation.

Filtering List Operations

For consistency across APIs, I use query parameters to, as the name implies, parameterize the query. What does this mean? Most commonly, I use query parameters to serve as filters on List operations, as a means of subsetting the response list to a narrower set that satisfies the conditions defined in one or more query parameters.

In these cases, the interpretation of the query parameters is done with an implicit context of an element of the referenced collection.

In our Chain Links API, one such collection is the chainLinks resource.

A chain link has several properties:

• the author who created/write the chain link
• a set of characters who are mentioned in or are part of the chain link
• the universe in which the chain link occurs
• the date when the author create/wrote the chain link (authoredOn)

Thus, we can use these property names as query parameter names to subset the list response to those chain link instances whose property values match the query parameters.

The next design decision is what query parameter values to use after the = sign. For author and universe query parameters, we want to allow the client to pass the author’s resource ID (author names are not unique) or perhaps the author’s URI. Similarly, it is most convenient for the client to pass the resource ID for for a universe resource.

As I wrote in From Domain Model to OpenAPI, one can parameterize the request to return a list of chain links:

GET /chainLinks?character={someCharacterId}
GET /chainLinks?universe={someUniverseId}
GET /chainLinks?author={someAuthorId}
GET /chainLinks?authoredOn=[2023-01-01,2023-03-31]

I hope the first three are intuitive. A common pattern is to filter resources on a range of values, such as a date range. In banking APIs (such as filtering a list of transactions), it’s common to filter based on a range of values. I like using range notation as shows with the date range above; this works for numeric values as well, such as GET /banking/accounts/{accountId}/transactions?amount=(0,100.00] to match transactions whose amount is greater than 0 and less than or equal to 100.00.

I’ve seen lots of other query designs for ranges, such as

?amount=gt:0&amount=le:100.00
?filter=and(gt(amount,0),le(amount:100.0)
?where=amount > 0 and amount <= 100
?$filter=amount gt 0 and amount le 100.00

The last one is based on OData. It and the ?where style before it are more common in APIs which directly expose the underlying data schema. However, this is more of an anti-pattern in modern web APIs, which are more robust when they support (or even enforce) an abstraction layer between the API consumer and the back-end system behind the API. Mike Amundsen put this eloquently when he wrote

Amundsen’s Maxim “Remember, when designing your Web API, your data model is not your object model is not your resource model is not your message model.” — Mike Amundsen

(Mike shared this in 2016 on a social media microblogging site that I choose to not quote here. However, you can read more about it at What is Amundsen’s Maxim?)

In other words, if you expose the current data schema of your (internal) database, you lock your API into that implementation, or you risk breaking clients if you wish to refactor the database. (Mike followed up the original message with a clarification: “we need to be able to design/implement each aspect (data, object, resource, representation) independently without breaking the others.”) Thus, I advise against adopting any query parameter patterns that expose the back-end implementation details of the API web service. I think this emphasizes the main purpose of following good API design and API design patterns: Expect change, and use API design to hide the API consumer from changes which should not impact them.

Getting back to our other patterns, I hope you can see why I think that interpreting = in a URL’s query parameters as “is” works better than “equals”, such as:

?amount=gt:0&amount=le:100.00

amount is greater than 0 and amount is less than 100.00

Some of these obviously require URL encoding, namely:

?amount=(0%2C100.00%5D       // ?amount=amount=(0,100.00]
?amount=gt%3A0&le%3A100.00   // ?amount=gt:0&amount=le:100.00
?amount=and(gt(amount%2C0)%2Cle(amount%3A100.0)
?where=amount%20%3E%200%20and%20amount%20%3C%3D%20100
?$filter=amount%20gt%200%20and%20amount%20le%20100.00

Unfortunately, none of these are very legible once they have been URL encoded.

I like the range notation (also known as interval notation) because it has existed in mathematics since before I first studied math (decades ago). It is concise and very flexible. The ( and ) characters denote open ended intervals (the interval does not include the adjacent endpoint) and the [ and ] characters denote closed-ended intervals (the interval includes the adjacent endpoint):

?amount=(20.0,100.0]  : amount > 20.0 && amount <= 100.0
?amount=[20.0,100.0]  : amount >= 20.0 && amount <= 100.0
?amount=(20.0,100.0)  : amount > 20.0 && amount < 100.0
?amount=[20.0,100.0)  : amount >= 20.0 && amount < 100.0
?amount=(20.00,)      : amount > 20.0
?amount=[20.00,)      : amount >= 20.00
?amount=(,100.0]      : amount <= 100.00
?amount=(,100.0)      : amount < 100.00

This or That, Here or There

One additional query parameter pattern I use comes in handy when you wish to express a condition where a resource’s property is one of a small list of values (usually string enumerations). I.e. to capture the condition of testing if the state property of a chain link is one of three values, draft, published, withdrawn, the desired natural language query is something like

List chain links where the chain link’s state is either draft or published or withdrawn

As a query parameter, the OpenAPI Specification allows defining a query using an pipe-delimited array. This is convenient because the pipe character, |, is used as a binary or operator in several programming languages. Thus, this filter maps to query parameter notation

?state=draft|published|withdrawn

In OAS 3.x notation, one can define a parameter:

parameters:
  - name: state
    in: query
    explode: false
    style: pipeDelimited
    schema:
      type: array
      minItems: 1
      maxItems: 3
      uniqueItems: true
      items:
        $ref: '#/components/schemas/chainLinkState'

The chainLinkState schema is defined with a JSON schema such as

components:
  schemas:
    chainLinkState:
      title: Chain Link State
      description: The state that a chain link resource may be in.
      type: string
      enum:
        - draft
        - published
        - withdrawn

The schema for the query parameter further constrains the parameter, allowing an API service to validate the value and reject invalid queries such as

?state=                         # minItems constraint violated
?state=garbage                  # items enum constraint violated
?state=draft|draft|draft|draft  # maxItems / uniqueItems: true
                                # constraint violated

I prefer using named schemas for such cases compared to putting the enum schema in line in the parameter definition, as this helps Software Development Kit (SDK) code generation tools generate cleaner code. Absent named schemas, code generation tools often construct new names for data types based on the context or location, and I find the result somewhat unsatisfactory.

Parameterizing Operations

Query parameters can parameterize other operations, not just List operations. I try to avoid mixing request body data with parameterization. For example, when creating (POST) or updating a resource (PATCH or PUT), I put all the data necessary to create or update the resource in the request body. Query parameters may alter how the operation is performed, but the request body conveys what data to use.

For example, see how the ?dryRun= query parameter alters the behavior of a POST or other operation in Validating API Requests. There, the value of the ?dryRun= query parameter is not part of the request body payload — it does not get stored in the resource. Instead, this parameterizes the operation, requesting that the server stop short of creating or updating the resource, so that the client can let the API service perform full validation of the request.

Your Options

There are many conventions and patterns for Web API query parameters. It’s less important which style you choose, but as with any pattern, what is more important is that you use it consistently across your APIs.

Join the discussion

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

Hypermedia as the Engine of Application State

It’s finally time for API Design Matters to tackle one of the more complex API design patterns/practices: Hypermedia, or more aptly named, Hypermedia As The Engine Of Application State (HATEOAS).

(Please note that what follows are my personal observations and perspectives on Hypermedia APIs. I encourage API Design Matters readers to explore other voices.)

Roy Fielding defined the REST API architectural style and has stated that an API is not a REST API if it is not hypermedia driven. So what does this mean?

( REST? RESTful? REST-like? REST-ish? See We Talk “API” One Day )

At the structural level, a Hypermedia API is one in which the capabilities of the API—or more accurately, the capabilities of the application that the API enables—are conveyed in the API’s responses, typically through hypermedia links embedded in the data. Much as a web page is more useful because it contains links to other related web pages, an API response (that is, a representation of one of the API’s resources) is enriched when it includes links to resources or API actions related to that resource.

Hypermedia APIs allows both discoverability of the features of the API/application as well as looser coupling between the client application and the API services—both admirable goals. As a pattern, Hypermedia is fine solution to the design force of decoupling a web application front end from the back end that manages it. Key to this is allowing business rules to be managed on the back end rather than replicated in the front end. For example, by including or excluding certain links in responses from the back end, the application can control what the end user can do. More importantly, it allows the application to evolve by adding new features, expressed through hypermedia, without having to re-write or update the client.

However, just as there is no standard definition of a REST API, there is no definitive standard for how such hypermedia links are conveyed. Instead, there are myriad competing standards and formats, such as

• Hypertext Application Language (HAL)
• Siren
• Restful JSON
• Collection+JSON
• JSON-LD
• JSON:API
• Hydra
• … and others.

I won’t dive into the details of all of these (that would be a couple chapters worth of book material, and not too helpful right now). Instead, I want to discuss the pros and cons of embedding Hypermedia in a web API.

One of the primary goals of encapsulating a back end service or process with an API is to add a level of abstraction. The API is the embodiment of an abstraction at a point in time. However, services evolve over time - they may add more capabilities or features. This is typically exposed with new versions of an API, or even entirely new APIs if the new behavior does not fit well in the existing API.

However, another way to deliver new functionality within an API is more dynamically, by returning new links in the payload of the existing API.

For example, in the Chain Links sample API I have provided in this series, the listUniverses operation returns a representation of a list of universes (i.e. an array of universeItem objects, each of which has the unique id of a universe.) The getUniverse API operation accepts a universeId path parameter and fetches the representation of that universe. This requires the client (or a Software Development Kit or SDK library) to construct URLs to use the API - i.e. the getUniverse(universeId: string) operation will substitute the universeId into into the API path /universes/{universeId} and prepend the API server base URL from the OpenAPI servers object in order to invoke the getUniverse operation, then parse the JSON response and bind it to a universe data structure in the target language. In a hypermedia API, the URL of each item would be included in the list of universe items in the listUniverses’s universes response, so that the client is more loosely coupled to the API. This allow the API service to evolve over time, such as providing a more efficient URL for fetching resources. Such changes are not possible if the client has a tight coupling to (a specific version of) the API.

The other challenge with hypermedia links is conveying the semantics. At the base level, a link is just that - a URL. But in an HTTP API, a URL is only part of the operation: there is also the HTTP verb, the authorization, the request and response bodies, HTTP request and response headers, and if the client is going to present the link or action in the client application (such as a button or menu item or link), it requires a title or label or descriptive text. Unadorned Hypermedia links may work well with GET operations, but less so with POST operations.

A key element of that unwieldy name “HATEOAS” (_H__ypermedia __A__s __T__he __E__ngine __O__f __A__pplication __S__tate) is _Application. Hypermedia APIs work well when they are part of a web application. Applications have state; they combine user input and back end processing, and the API encapsulates that application’s behavior and capabilities. In such cases, these HATEOAS APIs can contain links that expose or enable the next possible steps in the application, based on the current state of the application and what the authenticated user can do, given that application state and what roles and permissions that user has. For example, from a list of application domain objects, there may be an “edit” link which allows the user to edit that object. Lack of such a link means that the current user, given the current application state, cannot edit the object. The appeal of this decoupling is obvious - the client application does not (and rightfully should not) contain such business rules, as these are subject to change (perhaps at a cadence more frequent than API version releases).

Supporting a Hypermedia API is of course most useful if the client application is written in such a way that it can do something with those dynamic links. This is no easy task… most application developers don’t want to deal with that kind of complexity.

However, we are all familiar with one type of such dynamic application - your favorite web browser. This ability to handle arbitrary links and dynamic content is what allows the browser to host myriad client applications, such as Gmail, Substack, LinkedIn, and so on… without having any prior knowledge of those applications.

However, when an API is the front end of a very general and reusable web service with a well defined functional boundary (such as sending Email or SMS messages or making a credit card payment for an purchase), there is not a single application that the API is attached to - it must work with arbitrary applications. Such atomic and composable service APIs may be stateless, and since they are not part of any one specific application, they have less application state to convey, and hence HATEOAS links are less impactful for conveying application state. Related resource links are still useful, such as a link from a Chain Link Character to the Universe in which that character lives.

I suggest reading Bruno Pedro’s article, Why Aren’t APIs Using Code on Demand? in The API Changelog. Bruno’s article discusses one of the (optional) constraints of the REST architecture style, namely Code-on-Demand. It is what makes an API driven application (such as a single page application) powerful and reactive, compared to older web application architectures which are built around server-generated web pages. Code-on-Demand works for web applications because such applications run within an application host (a browser) which can execute that code.

Code-on-Demand is also necessary to fully interpret the links in a Hypermedia API. For example, consider a resource in our Chain Links application, a Universe. How does one add a new universe? Certainly the API answer is trivial - by using the POST operation on the /universes collection, passing a request body that satisfies the newUniverse schema. In a hypermedia API, the universes collection resource may have a hypermedia link with a link relation called createUniverse, but if a client application does not know about this resource or which request body schema is needed to create a universe, it can’t use that link… just as a client coded to version 2.1 of an API has no knowledge of a resource introduced in version 3.0 of the API.

However, Code-on-Demand will allow the application to fetch the code to do new things, such as create a universe, edit a universe, update a universe. Creating can be done via a link to a web page or form or applet which prompts the user to fill in and submit the data necessary to complete the request. That is, the link to create a new universe is may be a link to a web page — part of the broader application that the API encapsulates. It may contain UI form controls and JavaScript to handle the dynamic aspects, and perhaps optional controls based on the current application state, such as where to go next after completing the current task, or where to return to if the user decides to cancel. In such a way, the client is adaptable and not tied to a specific version of the API - the application, the API, and the client can evolve together.

The downside is that, as it’s name implies, Code-on-Demand requires passing executable code from the back end to the front end. If the client is a browser, it can dynamically load JavaScript as part of rendering a web page. Other clients may not have this dynamic capability. If the client is a secure back office headless application written in some other language such as Go, it can’t use such Code-on-Demand without adding a lot of complex client code execution features. (Of course, security must also be considered any time an application introduces a new code execution feature.) Also, I am not aware of APIs which support languages other that JavaScript, though using WebAssembly (see Why Aren’t APIs Using Code on Demand? ) may be the technology bridge.

Developing clients to consume and fully exploit Hypermedia APIs requires not just handling Code-on-Demand; it requires a different mindset. That is, one must consider the API to be a dynamic entity, not a static one, with new features possible every time an API call is made. This is a difficult thing to implement well or correctly, especially when many applications are often written to do very specific things.

For example, the AI summary on the Gmail API page states (as of Jan 19, 2025):

The API is not intended as a full email client replacement but is ideal for web applications needing authorized access to user data.

Most developers prefer using some sort of language Software Development Kit when coding to an API. However, these SDKs are often tied to a specific version of an API, with a specific URL layout and fixed set of operations and parameters—this goes very much against the grain of Hypermedia APIs which are meant to be dynamic and flexible, not strictly rigid structures with statically defined URLs and statically defined request and response body schemas. Such SDKs (often generated from an OpenAPI definition) typically use rigid interface constructs, such as representing path parameters (which the SDK will inject to API resource URLs) as function parameters, with one function per API operation. But a Hypermedia application is more dynamic - the URLs are all provided by the API, so the client should never construct a URL. (For example, the getUniverse function in an SDK for a static API may accept the universeId parameter; for a Hypermedia based API, the getUniverse function in an SDK may accept the universe’s URL as a parameter instead (where that URL is obtained in a link within another API response.)

Let’s revisit an application like Gmail. How would you design this application to automatically support dynamic features that were not in your requirements when you first started?

For example, Gmail allows adding attachments to a mail message; that is part of the mime message format. The user can select a file from their local file system and the client encodes that in the email message body. However, if the file is too large, Gmail now has the ability to upload the file to Google Drive (and set the permissions on that file so the recipient can access it) and instead of adding an attachment, Gmail will insert a hyperlink to that file on Google Drive. Imagine trying to design the client app to allow executing this type of dynamic behavior - it is not trivial. But with Code-on-Demand, it is possible.

Yes, hypermedia APIs are a useful replacement for server generated web page architecture, and decoupling a (browser) web application from back end logic and business rules. HATEOAS seems a better fit when there is a (server managed) web application, but harder to exploit when the API is a general purpose component meant to be embedded in arbitrary applications that the service knows nothing about.

Join the discussion

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

Make API responses more self-descriptive with reference objects

Here’s today’s quick tip to make your API really stand out: make the response payloads as cryptic as possible.

I’m kidding, of course. I suppose if your message models are super cryptic, your API will stand out… but for the wrong reason. Today, I’ll present a useful pattern for making API data less cryptic with the equivalent of a “calling card” - API reference objects.

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.

Most api resources don’t exist in isolation - instead, they have relationships with other resources. in the api design matters sample domain, chain links, i’ve shown how to use restful json to capture these relationships. a chain link has an author, and in the json model of a chain link, there is a property

  "author_url": "https://api.chainlinks.example.com/authors/a733fhab"

which is the URL of the author resource. A chain link also resides in a universe that is conveyed with a property as well:

"universe_url": "https://api.chainlinks.example.com/universes/ucc87e09"

If not using Restful JSON or some other hypermedia based format, these relationships may be modeled instead with the lower level equivalent of foreign database keys, namely the resource IDs of the related resources:

"authorId": "a733fhab"
"universeId": "ucc87e09"

While these representations convey the necessary information, it’s not very satisfying for human consumption and results in a poor developer experience.

I prefer JSON representations which are less cryptic and more self-descriptive. This is where small reference objects can be useful.

My use of the term “reference object” is only slightly related to a $ref reference object as used in JSON Schema and OpenAPI Specification (OAS). In OAS, a Reference Object is a JSON object with a $ref keyword and a URI of a referenced value defined elsewhere in the OAS API definition. (See Don’t Repeat Yourself When Designing APIs ) For example, an API operation’s response object may define the response’s schema with a Reference Object to a schema component. The getAuthor operation’s 200 OK response is defined with a $ref to the author schema:

      responses:
        '200':
          description: OK. The operation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/author'

In OAS, a reference object contains a $ref value and may contain summary or description values. However, there is a kernel of usefulness here that can be used outside of defining an API with OpenAPI — we can use a construct inspired by OAS reference objects instead of terse and cryptic Restful JSON URLs or naked resource ID properties.

An API reference object is a (JSON) object that references another resource.

Such API reference objects (or more simply a reference object) in API responses (or requests) can include other key identifying data about the referenced resource; these are optional and informative. The id or url of the resource are required to actually identify the referenced resource. This makes the overall JSON payload more self-descriptive and does not send the developer down ratholes trying to understand data they see when exploring and learning the API.

Instead of seeing a terse/cryptic representation of a chain from the Chain Links API:

{
  "id": "36abf4ceb72389",
  "author_url":
     "https://api.chainlinks.example.com/authors/a733fhab",
  "universe_url":
     "https://api.chainlinks.example.com/universes/ucc87e09"
  ...
}

we can use reference objects (a different reference object schema for each resource) that includes the resource ID of that resource, its URL, and other identifying data:

{
  "id": "36abf4ceb72389",
  "author": {
     "name": "D.T. Weintraub",
     "id": "a733fhab",
     "url":
        "https://api.chainlinks.example.com/authors/a733fhab"
  },
  "universe": {
     "name" : "Edgar Rice Burroughs' Mars",
     "id": "ucc87e09",
     "url":
        "https://api.chainlinks.example.com/universes/ucc87e09"
  }
  ...
}

While a bit more verbose, I find the extra data to be immensely useful in understanding the overall data.

In my work with designing banking APIs, we use account reference objects when one resource has a relationship to a banking account. For example, a transfer from a source account to a target account can be represented (albeit cryptically) as

{
  "sourceAccountId" : "30623674-5a14-99eed7a86549",
  "targetAccountId": "4f3775d0-94e5-39cb8fb6924d",
  "amount" : "500.00"
}

By itself, this is not very informative because the opaque resource IDs do not add much usable stand-alone information to the reader; all we have is the means to find out more information about those accounts, but that is indirect and cumbersome.

A much more descriptive representation uses account reference objects which tell more about the accounts:

{
  "sourceAccount" : {
    "id": "30623674-5a14-99eed7a86549",
    "url" :
      "https://api.example.com/accounts/30623674-5a14-99eed7a86549",
    "type" : "checking",
    "maskedNumber" : "*7844"
  },
  "targetAccount" : {
    "id": "4f3775d0-94e5-39cb8fb6924d",
    "url" :
      "https://api.example.com/accounts/4f3775d0-94e5-39cb8fb6924d",
    "type" : "savings",
    "maskedNumber" : "*1363"
  },
  "amount" : "500.00"
}

Resources can contain their own reference objects

To make these reference objects even more useful, the API service can build them for you instead of making the client construct them. For example, the response from the getUniverse operation can contain a reference or ref property which is the reference object that the client can embed in other requests when citing a universe. The *Item schema in the API’s list responses (see What Am I Getting Out of This?) can also include the reference object instead of just the id of the item in the colletion.

Avoiding Excessive Data Exposure

Reference objects should be small and only contain necessary data, not many or most of the properties of the referenced resource. For example, by no means is the universe property of a chain link defined by the full universe schema. This limited, small reference object helps avoid Excessive Data Exposure (OWASP API Security 2023 “Broken Object Property Level Authorization” vulnerability. Using small reference objects helps keep payloads smaller but still informative. Too many properties will just add noise, defeating the Developer Experience benefits of using reference objects. Choose key attributes of the resource to include in the reference object, such as the name or type of the resource. Avoid sensitive data, such as full account numbers, sensitive Personally Identifiable Information (PII), etc. (Note: the author name shown in examples above is not PII, but is the author’s public pen name.)

I hope you see value in using reference objects over more cryptic and opaque identifiers or URLs. Why not try them out in your next API design? Please leave comments to share your experience.

Join the discussion

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

Techniques for API Request Validation

Next up in the API Design Patterns series on API Design Matters, I’d like to present some patterns for validating API requests.

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.

As I discussed in Improve the Security of Your API’s Data:

An API that allows unconstrained values to be passed is an API that likely has security vulnerabilities

That is, to keep an API secure, it should not trust any data that it receives. Applying strict JSON schema constraints and ensuring all API operations are properly secured via authentication/authorization help with maintaining the secure API posture. But is there a flip side - can an API help client’s validate their interactions with the API?

A promise of REST APIs is good decoupling of clients and services. This is achieved in part by reducing business logic as much as possible in the client application. For example, a client application may use a form for collecting information used in a POST operation to create an API resource, or to edit an existing resource before updating it with a PUT or PATCH operations. The client then maps the form fields to the properties of the operation’s request body. Clients can use front end frameworks and libraries to perform lots of low-level validation in the front end corresponding to JSON schema constraints. Examples include:

• Forms which use required data fields for properties that are required in the JSON schema
• Using date pickers
• Checkboxes for selecting Boolean true or false values
• Drop down lists that allows selection from a list of fixed enum values
• Constrained numeric text entry
• Form fields that enforce a regular expression matching of input from a pattern constraint

However, this only covers “syntactic” or static field-level validation. Often, an API will also have business rules that the client must follow. Secure API services will enforce those business rules in the API operations - for example:

• Parse the options and (JSON) request body and return a 400 Bad Request if any of the request data is malformed (i.e. does not satisfy the constraints of the operation—such as required body or required parameters—or all the JSON Schemas associated with the operation’s parameters or request body)
• Verify that the caller passes valid Authorization to the API call, and return 401 Unauthorized if not
• Verify that the caller is authorized to perform the API operation, and return a 403 Forbidden error if not.
• Verify the state of the application and return 409 Conflict if the operation would put the application into an inconsistent state
• Verify the semantics of the request body and return a 422 Unprocessable Content error if the request is incomplete, inconsistent, or otherwise invalid

However, such problem responses only occur “after the fact” - they are returned after the client has made an API call. Many of these checks cannot be made by the client at all—for example, the client cannot validate a OAuth2 access token.

Can the API help the client prevent errors by performing business logic and other validation for the client, so that such business rules do not have to be embedded in the client?

One pattern is to extend the API operations with a dry run feature. A dry run is a variant of the API operation which performs all (and only) the validation performed by the full operation, but does not execute the associated behavior. As such, it will return the same 400/401/403/409/422 that the full operation would return, allowing the client to highlight invalid form data or otherwise correct the problem. The client can use dry run operations incrementally as the user fills out a form, and disable the “Save” or “Next” or “Submit” or similar UI controls if there are validation errors.

One way to implement a dry run is to create a separate “validation” operation for each API operation. This has the significant disadvantage of greatly increasing the footprint (size) of the API and adding a lot of duplication.

Rather than duplicate operations to add sibling validation operations, another approach is to add a

?dryRun=true

query parameter to the operations. When used, the operation can return 204 No Content if the request contains no problems. The dryRun parameter acts as a “short circuit” in the API operation. The implementation performs the full validation it would normally do before executing the desired behavior, but then stops before actually executing anything other than the validation.

This pattern has a small impact on the API footprint compared to making sibling (duplicate) validation operations. A smaller footprint makes the API easier to read and understand. It is also a good use of the DRY principal , since you do not have to duplicate the definition of all the operation request parameters and request bodies, which opens up the chance for them to become out of sync. You do not have to invent a new operation ID or create a new API path for each operation.

For example, here is how to add a dryRun query parameter to the OpenAPI definition, within the createCharacter operation to create a new character in the Chain Links sample API:

paths:
  '/characters':
    post:
      title: Create a Character
      description: >-
        Create a new Character. Use ?dryRun=true to perform validation
        of the data without actually creating a character.
      operationId: createCharacter
      parameters:
        - $ref: '$/components/parameters/dryRunQueryParam'
          description: >-
            If `true`, this operation only validates the request and
            it's data but does not actually create a character.
            The operation returns one of the defined 4XX errors
            if there are any problems, or
            returns 204 if there are no problems.
      security:
        ...
      responses:
        '204':
           description: >-
             No Content. There are no validation errors
             with the request data.
        '201':
           description: Created
           ...
components:
  parameters:
    dryRunQueryParam:
      name: dryRun
      in: query
      schema:
        type: boolean
        default: false
      description: >-
        If `true`, this operation only validates the request and
        it's data but does not execute the remainder of the request.
        The operation returns one of the defined 4XX errors
        if there are any problems, or
        returns 204 if there are no problems.

It is hard to make a completely generic dryRun parameter component because the description should be specific to each operation where it is used. In this case, I’ve used a component parameter dryRunQueryParam, but provided a context-specific description of the dryRun parameter for the createCharacter operation.

There is another API pattern that addresses these problems in a completely different way. The definition of a true REST API — Level 3 in the Richardson Maturity Mode — is Hypermedia as the Engine of API State, or HATEOAS. An important component of HATEOAS is “code on demand”, whereby the API service returns code to the client which can implement application logic. This can include performing some business logic checks/validation without such business logic being hard-coded in the client. I’ll tackle HATEOAS in the future.

Join the discussion

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

Patterns for naming things in APIs

While CRUD may be the most common pattern in RESTful APIs, how to name things sure seems to be the most talked about.

Next up in the API Design Patterns series on API Design Matters, I’d like to present a common pattern for managing API resources.

Certainly, one can name API elements without following any pattern…. that will likely yield unfavorable results. As I noted in my The Art of API Design presentation at the 2024 Nordic APIs Austin API Summit, you could get creative and start using musical notes or Greek letters to name things… but that will hinder the usability of the API. In other words, applying consistent naming patterns will increase the usability of your API… and that won’t hurt adoption.

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.

Matthew Reinbold posted in Net API News in September 2023 about The Necessity of Naming in APIs:

“naming should convey the API producer’s mental model to many consumers with minimal fuss” — Matthew Reinbold

“To lower the cognitive overhead required to integrate with your API, you must consider naming design issues. It is the #1 thing that an API producer can do to improve a design, always.” — Matthew Reinbold

Matthew lists serval factors that contribute to the long-held (and justifiable) belief that naming is hard, then recommends a book, Naming Things: The Hardest Problem in Software Engineering by Tom Benner.

So there is a lot of good advice on choosing domain names for your API. I’m going to step back and suggest naming patterns in APIs to improve the developer experience. Using consistent naming patterns (or using any pattern consistently, when it is the right pattern) will help lessen the cognitive load when others try to adopt your API. But consistent naming will also help you in the design process—basically, a naming pattern serves as a preemptive design decision that removes the need to make lots of similar decisions in the rest of the API design process.

For example, here is a list of the important (OpenAPI) API elements that require a name from the API designer:

• Path elements
  • static path elements
  • dynamic path elements - path parameters
• Operation IDs
• Requests and Response Headers
• Query Parameters
• Schemas
  • schema names
  • object property names
  • string enumerations
• Response objects
• Parameter objects
• Security Schemes
• Security scopes

With each name, you have a some important name attributes to consider:

• Style — do you use snake_case, camelCase, PascalCase, kebob-case (something else?)
• Is the name case sensitive or case insensitive? Both OpenAPI and HTTP sort of make this decision for you - most names in the OpenAPI Specification are case sensitive. However, HTTP says that header names are case insensitive. The convention adopted in many revisions of the HTTP standards are to use Title-Kebab-Case for headers, such as Content-Type, Content-Length, Retry-After, and so on.

Rather than defining a separate naming rule or pattern for each category (I count 14 naming categories above), I have adopted a meta rule for API design: Unless otherwise indicated, use camelCase style for all names, with the exception of header names, which should follow the Title-Kebab-Case style described above. (Every rule needs an exception, so that you can claim a small bit of edginess or sense of rebelliousness.) I prefer using camelCase because such names can be used as programming language identifiers in most programming languages without transformation rules, and OpenAPI also uses it throughout (for example operationId, securitySchemes, requestBodies, etc. — perhaps for the same reason :-) )

This does not cover all naming situations. Heres a few more naming patterns—beyond the purely syntactic style pattern— that I have adopted:

URL Paths

• I use plural names for the domain resource (entity) collections, such as (in our API Design Matters Chain Links sample application’s domain example): /chains, /chainLinks, /authors, /universes, /characters, etc. (Note how the compound-word resource term “chain link” becomes chainLink via the camelCase style). Others prefer using kebab case for path elements (i.e. `chain-links). This is perfectly valid, although it deviates from the “one pattern to rule them all” that I prefer. This is a matter of preference and style, so choose one rule and use it consistently throughout your API.
• For path parameters which indicate the unique resource ID of an instance within a collection, I use a <resourceName>Id naming pattern: /chains/{chainId} , /chainLinks/{chainLinkId}, /authors/{authorId}, /universes/{universeId}, /characters/{characterId}, and so on.

Operation IDs

The operationId assigned define in each operation object is often used in code generation as the name of a function or method to invoke the operation. Thus, I start all operationId names with direct present-tense imperative verbs, such as listAuthors, createUniverse, getCharacter etc. I use list for operations that return lists or collections of API resources and get for operations which return individual instances within collections or other non-collection resources.

Model Schemas

The model schemas in APIs are the names of things and thus should use nouns or noun phrases, such as author, character, universe, chain, and chainLink. For convenience thoughout API Design Matters, I’ll use a generic camelCase placeholder {resourceName} for the name of an API resource when talking about naming patterns, not about a specific API resource. The case here is significant. For example, for the “chain link” domain resource for the Chain Links API, {resourceName} is chainLink and {ResourceName} is ChainLink.

Here are the API naming patterns for model schemas (used in request and response bodies):

• new{ResourceName} is the name of the model schema used (via a POST operation) to create a new instance in the create operation. Example: newChainLink is the request body to create a new chain link.
• {resourceName}Patch is the name of the model schema used for the for a PATCH operation request body. Example: chainLinkPatch is the request body to patch an existing chain link.
• {resourceName}Update is the name of the model schema for the PUT operation request body to replace a resource with a completely new representation.
• {resourceName} is the name of the model schema normally returns from a GET operation, or in the response from the create or patch or replace operation, such as chainLink.

By applying these model schema naming patterns with the operation ID and path element patterns, larger aggregate patterns become evident.

To create a resource:

POST .../{pluralResourceName}
operationId: create{ResourceName}
request body model schema: {newResourceName}
response body model schema: {resourceName}

For example:

POST .../characters
operationId: createCharacter
request body model schema: newCharacter
response body model schema: character

Property Names

In general, the names of properties in an object model should use the names from your domain model and ubiquitous language. However, there are a number of commonly repeated property names which pop up, regardless of domain. Having “reserved” property names as part of your API pattern language can guide your consistent API design:

• id — the unique identifier (string ID) for a resource, often automaticalluy assigned by the API service in the POST operation that creates a resource. This id is used in the .../{pluralResourceName}/{resourceName}Id resource path to access the instance resource within the collection, such as .../characters/{characterId} or .../authors/{authorId}
• createdAt is an RFC 3339 date-time when a resource was created.
• updatedAt is the date-time the resource was last updated with a PUT or PATCH or other transformation operation. In general, I suggest using {event}At for date-time properties and {eventAt}On for date properties when the time of day is too precise and only the date is needed.
• The property name is for resources which have names (often names which people assign to them); label for resources which have slightly longer word-phrase labels that are displayed in the user interface; and description for resources which allow longer sentence-length or paragraph descriptions).

Meta Patterns

Name Everything

My preference is to provide names for all API elements, especially schemas — avoid using anonymous nested schemas (i.e. if a property p within an object schema s is defined by another object schema (or array of objects), do not define the schema for s in line. Instead, extract them to a named schema. This is important for code generation (Software Development Kits or SDKs) for your API, as different vendors choose different “automatic” naming strategies for any anonymous/unnamed schemas, and this can diminish usability of the SDK and therefore the API. Such auto-generated names can often be overly long and cumbersome because they tend to be derived from the context.

This applies not only to schemas nested inside other object schemas or array item schemas, but to response object schemas, request body schemas, parameters, and subschemas used schema composition with allOf.

Naming the schemas also makes it much easier to reuse a schema later, and helps prevent code duplication and “API drift” — For example, if someone reading the API later sees the same object structure with the same four properties defined two or more times, natural question arise:

1. Are these the same structures?
2. If not, why not?
3. Is the similarity accidental?
4. What is different about them?

Naming such schemas helps has several benefits¹ :

• It reveals your intention
• It eliminates the need for such questions about your design
• It removes the need for copy and paste (and copy and paste errors – see Don’t Repeat Yourself When Designing APIs)
• It makes future maintenance and API evolution easier

Use widely recognized domain names : your ubiquitous language

If you have used the ADDR process or domain-driven design and created a ubiquitous language—especially one that is driven by external API consumers and feedback, that is a great starting point for the names in your API. I encourage you to review your API domain analysis and your API Domain’s ubiquitous language and choose names from that common language, provided they are clear and not based on jargon that is not really part of the domain.

Use Standard Names

When there is an existing internet standard, use the names defined by that standard. This begins with the HTTP standard (for example, for header names such as Content-Type, Accept, Accept-Language, Retry-After), media type names such as application/json, application/pdf, text/plain, etc.

If you are using application/problem+json (RFC 9457) representation for API problems/errors, use the property names it defines (type, status, title, detail, instance). ( Your API Has Problems. Deal With It. )

Few things will irritate a developer more than an API which does not follow existing standards.

Anti-Patterns

Avoid Brand Names

One thing that I’ve learned over more than 35 years working in corporate software development is to avoid using brand names or marketing names in API element names.

Brand and marketing names change over time—it is a fact of software development. If you incorporate brand/marketing names into an API, then the API becomes semi-obsolete when the name changes.

During my time working at one organization, I saw a single product renamed three separate times.

Always Avoid redundancy and repetition

When naming properties inside a model schema, avoid repeating the model name in the model schema’s property names. For example, use universe.id, character.name, and author.name, not universe.universeId, character.characterName or author.authorName.

Avoid Jargon

Another anti-pattern is using jargon, especially if such jargon derives from internal implementation choices such as code names, legacy systems, or terms that have seeped in from other domains. If the term is not in common use with a clear meaning understood by most domain practitioners and/or your API consumers, that is a strong hint that the name requires more thought. Better than writing documentation explaining why you chose a name, it’s better off to completely remove the need to ask such questions.

Summary

I’ve presented a small catalog of reusable patterns for naming elements of APIs. I hope they work for you, or at least inspire you to create your own patterns to increase the consistency and predictability of your APIs.

¹ Naming things gives you power over them. Or so I’m told.

Join the discussion

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