Use an API in unexpected ways

“You’re saying the highest form of a good API is when it gets used in ways nobody intended,” wrote Shane O’Connor in Off Spec nº 02. “How do you design for it without designing it away?”

Use a chair in unexpected ways. You can use a chair as a table, a step stool, a doorstop, a drying rack, and even an exercise helper.

Here’s my answer.

Found at “Off Spec № 02: Bruno Pedro on API Products, AI agents, and why DX isn’t the only thing that matters.” on 2026-10-29T15:46:33+01:00.

The ability to use a product in unexpected ways makes it more valuable to consumers. Let me give you an example of a physical product you can use for many different purposes: a chair. Something as simple as a chair can also be a table, a step stool, a doorstop, a drying rack for towels, or even, among other things, an exercise helper for doing triceps dips. How is that even possible?

In Product Design there’s an attribute we use to describe what’s happening with the chair: affordance. The chair, which is a flat, sturdy surface at knee height, affords sitting, but it also affords placing objects on it or standing on it. You don’t need a manual to know a chair can hold a mug or support your weight. Its physical form naturally suggests those possibilities.

With this information, designing an API so it can be “used in unexpected ways” starts by shifting away from task-oriented operations. Instead, offering resource-oriented operations is a better approach. Luckily, that’s exactly what REST preaches. The idea is to design operations so that they represent granular resources that can then be used individually or combined in totally unexpected ways.