Morphisms All the Way Down: API Design as Arrow-First Thinking

“In mathematics you don’t understand things. You just get used to them.”

— John von Neumann

Traditional architecture starts with boxes: services, databases, components. Categorical architecture starts with arrows: the relationships, contracts, and transformations between things. This shift from entity-first to relationship-first thinking transforms how we design systems. The arrows are the architecture.

Watch any architecture review. The discussion inevitably centers on:

• “What does this service do?”
• “What data does this database store?”
• “What’s the responsibility of this component?”

These are the wrong questions. They focus on objects when we should focus on morphisms.

Consider two architecturally identical questions:

1. “We need a User Service”
2. “We need these operations on user data: create, read, update, delete, authenticate, authorize”

The first answer gives you a box. The second gives you arrows. The arrows are what matter.

A “User Service” that exposes no operations is architecturally meaningless. But a set of well-defined operations? That’s a contract. That’s something you can implement, test, version, and evolve.

In category theory, a morphism $f: A \to B$ is a relationship from object $A$ to object $B$. The key insight: morphisms have more structure than objects.

Morphisms can be:

# Monomorphism: User ID → User (no two IDs map to same user)
GET /users/{id} → User

# Epimorphism: Every valid response is reachable
POST /users → User  # Can create any valid user state

# Isomorphism: Lossless encoding
JSON ↔ Protobuf  # If done correctly

# Endomorphism: State transitions
PATCH /orders/{id}/status → Order  # Same type in, same type out

# Automorphism: Reversible operations
PUT /users/{id}/toggle-active → User  # Toggle again to reverse

When you write an OpenAPI specification before implementation, you’re doing morphism-first design:

openapi: 3.0.0
info:
  title: Order Service
  version: 1.0.0

paths:
  /orders:
    post:
      summary: Create order
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

This specification defines a morphism:

The implementation is categorically invisible. Whether you use Node.js, Go, or COBOL³—whether you store in PostgreSQL, DynamoDB, or carrier pigeons—the morphism is the same.

In category theory, $\text{Hom}(A, B)$⁴ is the set of all morphisms from $A$ to $B$. This is extraordinarily useful for architecture.

For any two services $A$ and $B$, ask: what operations does $A$ invoke on $B$?

Coupling(OrderService, InventoryService) = {
  checkAvailability: Order → Availability,
  reserveItems: Order → Reservation,
  releaseReservation: ReservationId → Unit,
  decrementStock: Order → Unit
}

One precision: each operation above is a morphism between data types, so this set isn’t literally $\text{Hom}(\text{OrderService}, \text{InventoryService})$—every element of a hom-set must go from $A$ to $B$, and these don’t. With services as objects, each operation is instead one arrow $\text{OrderService} \to \text{InventoryService}$: four parallel arrows, with the payload typing living in the category of data types. That hom-set is the coupling surface.

This set tells you:

1. All the ways A can interact with B
2. The contracts that must be maintained
3. The coupling surface between services

Tight coupling = large $|\text{Hom}(A, B)|$

Loose coupling = small $|\text{Hom}(A, B)|$

If Service A has 47 different ways to call Service B, they’re tightly coupled. If there’s exactly one well-defined interface, they’re loosely coupled.

// Tight coupling: many morphisms
interface TightlyCoupledInventoryService {
  checkStock(sku: string): number;
  checkStockBatch(skus: string[]): Map<string, number>;
  reserveStock(sku: string, qty: number): boolean;
  reserveStockWithExpiry(sku: string, qty: number, ttl: number): boolean;
  releaseStock(reservationId: string): void;
  releaseStockPartial(reservationId: string, qty: number): void;
  getReservation(id: string): Reservation;
  listReservations(sku: string): Reservation[];
  // ... 15 more methods
}

// Loose coupling: minimal morphisms
interface LooselyCoupledInventoryService {
  checkAvailability(items: Item[]): Availability;
  reserve(items: Item[], ttl: Duration): Reservation;
  release(reservation: Reservation): void;
}

The second interface is easier to implement, test, mock, and evolve.

Design principle: Minimize $|\text{Hom}(A, B)|$ while maintaining required functionality.

This is the categorical formulation of interface segregation⁵ and loose coupling.

Before: One large API with many endpoints

Hom(Client, MonolithAPI) = { 50+ endpoints }

(Services as objects again: each endpoint is one arrow $\text{Client} \to \text{MonolithAPI}$.)

After: Multiple focused APIs

Hom(Client, UserAPI) = { 5 endpoints }
Hom(Client, OrderAPI) = { 8 endpoints }
Hom(Client, PaymentAPI) = { 4 endpoints }

Total endpoints might be similar, but each hom-set is smaller and more coherent.

If $f: A \to B$ and $g: B \to C$, then $g \circ f: A \to C$ exists. This is the composition law.

RawEvent → Parse → Validate → Enrich → Transform → Store
   A        f        g          h          i         j

The entire pipeline is a single morphism: $j \circ i \circ h \circ g \circ f: A \to \text{StoredEvent}$

1. Testability: Each morphism can be tested independently
2. Replaceability: Swap any stage without affecting others
3. Composability: Combine pipelines into larger pipelines
4. Reasoning: The whole is the composition of its parts

// Each stage is a morphism
const parse = (raw: RawEvent): ParsedEvent => { /* ... */ };
const validate = (parsed: ParsedEvent): ValidEvent => { /* ... */ };
const enrich = (valid: ValidEvent): EnrichedEvent => { /* ... */ };
const transform = (enriched: EnrichedEvent): TransformedEvent => { /* ... */ };
const store = (transformed: TransformedEvent): StoredEvent => { /* ... */ };

// The pipeline is their composition
const pipeline = (raw: RawEvent): StoredEvent =>
  store(transform(enrich(validate(parse(raw)))));

// Or more explicitly with pipe
const composedPipeline = pipe(parse, validate, enrich, transform, store);

When systems evolve, the key question is: are the morphisms preserved?

# v1
POST /v1/orders
Request: { items: [...], customer_id: string }
Response: { order_id: string, status: string }

# v2 - additive change (new optional field)
POST /v2/orders
Request: { items: [...], customer_id: string, priority?: string }
Response: { order_id: string, status: string, estimated_delivery?: date }

The v2 morphism is backward compatible because:

1. v1 requests are valid v2 requests (new field is optional)
2. v1 response consumers can ignore new fields

This is a compatibility square⁶: with the inclusion $\text{incl}: \text{Req1} \to \text{Req2}$ and extension $\text{ext}: \text{Resp1} \to \text{Resp2}$, restricting v2 to old requests factors through v1—$v2 \circ \text{incl} = \text{ext} \circ v1$. Project away the new response fields with $\text{proj}: \text{Resp2} \to \text{Resp1}$ and you recover v1 exactly: $\text{proj} \circ v2 \circ \text{incl} = v1$.

# Breaking change: different domain/codomain
POST /v2/orders
Request: { line_items: [...], customer: { id: string, segment: string } }
Response: { id: uuid, state: OrderState, timeline: [...] }

This isn’t an evolution of the same morphism—it’s a different morphism. The categorical view makes this clear: you’ve changed both domain and codomain.

Before any architecture review, enumerate the morphisms:

1. What morphisms exist? List every API, event, message, RPC call
2. What are their types? Domain → Codomain for each
3. Which are essential? Remove any morphism—does the system still work?
4. Which compose? Can you chain morphisms into pipelines?
5. What’s missing? Are there implied relationships not made explicit?

• Morphisms with unclear types: “This API returns… whatever the backend sends”
• Non-composable morphisms: “You have to call A, then call B with the result, then…”
• Duplicate morphisms: Three different ways to get user data
• Circular morphisms: A calls B calls C calls A

In the services-as-objects picture, an API Gateway maps external routes—arrows into the gateway—to internal calls:

Hom(ExternalClient, Gateway) → Σ Hom(Gateway, BackendService)

The gateway is a morphism transformer—it takes external morphisms and maps them to internal ones.

EventBridge is a routing engine:

Rule: Event → TargetInput   # restricted to events matching the pattern

Each rule is a morphism. But fan-out is not composition—rules sharing the same source can’t compose with each other. It’s tupling, the universal property of the product:

⟨Rule1, Rule2, Rule3⟩: Source → Target1 × Target2 × Target3

A state machine is a collection of morphisms between states:

Hom(State1, State2) = { transition1, transition2 }
Hom(State2, State3) = { transition3 }
...

The workflow is the composition of these state transitions.

Think in arrows, not boxes.

When designing systems:

1. Start with the morphisms (contracts, APIs, events)
2. Let objects emerge from what the morphisms require
3. Minimize coupling by minimizing hom-set sizes
4. Ensure morphisms compose cleanly
5. Evolve morphisms carefully—breaking changes break composition

The architecture is the collection of morphisms. Everything else is implementation detail.

Next in the series: The Yoneda Perspective: Systems Defined by Their Interfaces — Where we discover that knowing all the morphisms into and out of an object tells you everything about it.