chapter six

6 Reliable API Design:Public Contracts and Synchronous Communication

 

This chapter covers

  • Defining the API as a binding "Public Contract" between Client and Server.
  • Deciding between the rigid reliability of REST and the flexible query power of GraphQL.
  • Designing modern APIs specifically for AI consumption (LLMs and Agents).
  • Exploring the origins of REST and Roy Fielding's doctoral dissertation.
  • Implementing a clean, versioned API endpoint that honors the contract.

6.1 Introduction

In Chapter 5, we spent our time building a fortress. One with walls, a moat, and a drawbridge. All that was missing was a damsel in distress high up in the castle tower being held against her will by the king. Sorry, you’ll have to go play Super Mario Bros. if you want to rescue her from Bowser. We used Hexagonal Architecture to build a wall around our Domain Core, protecting it from the chaos of the outside world. We built "Ports" (airlocks) to ensure nothing could enter or leave without our permission.

But a fortress with no doors isn't a castle; it's a tomb.

Eventually, someone needs to use your software. A React frontend needs to display user data. A mobile app needs to submit an order. A third-party partner needs to pull a report. Or, increasingly common in today’s world, an AI Agent needs to query your system to answer a user's question.

How do we let them in without letting the chaos back in as well?

We build a Public Interface, commonly referred to as an API (Application Programming Interface).

6.2 The Client-Server Model

6.2.1 The Cost of Crossing the Line

6.2.2 The Separation of Duties

6.2.3 The Anatomy of the Conversation (Request/Response)

6.2.4 The "Clarity" Tradeoff: Thick vs. Thin Clients

6.2.5 Why We Split Them (Scale and Specialization)

6.3 API as a Public Contract

6.3.1 The "Restaurant Menu" Analogy

6.3.2 The Clauses of the Contract

6.3.3 The "Breaking Change" Nightmare

6.3.4 Hyrum's Law: The Hidden Contract

6.3.5 The Escape Hatch: Versioning

6.4 REST or GraphQL

6.4.1 REST: The Vending Machine

6.4.2 GraphQL: The Personal Shopper

6.4.3 Making The Defensible Decision

6.5 Designing for the New User: The AI Agent

6.5.1 The "Dumb Genius" Paradox

6.5.2 Naming IS Prompt Engineering

6.5.3 The Modern Architect's AI Rule

6.6 Diagram: Client-Server

6.7 Code Snippet: API Endpoint

6.7.1 Why This Matters

6.8 The Hidden Costs of Abstraction

6.12 Recap