I open a screen full of terminals, each in a different repository. Each one is one of my AI assistants, ready to accept tasks. I usually have two or three running at the same time, thinking, planning and acting. It looks like a scene from a hacker film. It is not — the repos are almost entirely Markdown. Three layers, and only one is disposableEvery AI assistant I run is set up the same way.

The moment it happensYou ship GET /pets. Someone asks to filter by status, so you add ?status=available. Then by species. Then someone wants cats or dogs, and a query string has no way to say “or”, so you invent something — ?species=cat,dog — and quietly decide that commas mean OR today. Then someone wants pets born after 2020, excluding the adopted ones, and you find yourself designing a grammar inside a query parameter.

A change is breaking if a client that worked yesterday has to change its code, its configuration, or its infrastructure to keep working today. That includes changes that keep every client running while quietly giving it wrong data — those are still breaking, only harder to notice. Most of the list below follows from one rule. On the request side, anything that narrows what the API accepts is breaking, because traffic that was valid yesterday must stay valid.

The shape is contractingProduct engineering got complicated for good reasons. Product managers to translate intent. Designers to translate experience. Engineers to translate constraints. Each role existed to own a part of the feedback loop process because no one person could hold all at once. At least not at scale. That is the assumption AI is dissolving. The translation layers between roles were never the work — they were the cost of distributing it across people.

1. Single responsibility works bestPeople tend to model agents on people: a product owner agent, an engineer agent, a QA agent. That fails for the same reason UserService failed. A role is not a scope. It is a bundle of unrelated jobs that share a title. Single-task agents hold up better. A backlog grooming agent. A release notes agent. A migration risk review agent. One job you can describe in a sentence, with a small tool surface and a clear output.

From building APIsI was always intrigued by APIs. Initially, I enjoyed building them. APIs of all kinds; functions, objects, Java interfaces, libraries, and of course, Web APIs. There’s something magical about encapsulating complex information and processes into a single interaction. To the business behind themI fell in love with APIs when I recognized their business significance. Giants like AWS, Twilio, and Stripe have leveraged APIs to build robust, scalable businesses.

Lay out the ContextAn API does not live in isolation. It is part of business, involves people, and may sit next to other APIs. All these are necessary to scope and design the API. Instead of that, you could create many integration pipes. It would be difficult to understand them all in a few years. Input: Interviews, relevant api designs, business & architecture diagrams, engineering docs. Identify the nonfunctional requirementsReview the security model & performance expectations.

For the last year, I have been working on what “better API design” means. How can we better design the public and our internal APIs? The term that comes to my mind to define this is maturity, thus API design maturity. What is API design maturity, then? When I searched on Google, most of the results were about the Richardson Maturity Model. Some results may refer to API-First and how an organization generally treats APIs.

IntroductionREST (OpenAPI) and gRPC are two of the most popular formats for APIs. REST is the style of choice of most public APIs, and gRPC is a popular alternative for internal APIs that need an efficient network. The OpenAPI Specification defines a standard to describe REST APIs and their capabilities. By default, gRPC uses Protocol Buffers, Google’s open-source mechanism for serializing structured data. The Protocol buffer schema is also an API specification.

IntroSuccessful digital transformation requires a focus on enterprise architecture, whether improving the system’s or application’s architecture or implementing strategies like API standardization. For an enterprise to practice architecture in an agile environment, several architects and designers must support the project’s agile value streams, which are the actions taken from conception to delivery and support that add value to a product or service. One organization may have a different team of architects producing solution designs and templates.