Api First vs Data First

Mike Adams

The Hidden Tension Between APIs and Data Models: A Case Study of Enumerations.

In the world of modern system design, there’s a constant debate between API-first and data-first approaches. While each has merit, the real challenge comes from how these two worldviews intersect — or collide — during actual product evolution. I recently encountered a perfect example that captures this tension: the humble customer title field.

The scenario

Imagine your product stores a “customer title” (Mr, Mrs, Ms) in the database. One day, the product team decides to support new titles like “Dr” and “Prof” to be more inclusive.

✅ In the database, this is easy: you add two more allowed values.

✅ In the domain, no problem — the real world can change.

But then a Slack message arrives:

“Hey, can you just update the API docs? We support an extended list of customer titles now.”

Sounds harmless. But then comes the API reality check.

The API problem

If your API contract explicitly defines an enumeration of permitted values — for example:

"customerTitle": {
  "type": "string",
  "enum": ["Mr", "Mrs", "Ms"]
}

— then adding new values breaks the documented contract. Clients who code against a strict list, with an exhaustive switch statement or strong type system validation, might fail in production the moment “Dr” appears. So what seemed like a simple data change becomes a breaking API change — requiring coordination, testing, versioning, and consumer communication.

Why does this happen?

This tension happens because:

  • Database people treat enumerations as flexible reference data.

  • API teams treat enumerations as public, locked-down contracts.

  • Clients treat enumerations as safe to hardcode.


These perspectives should align, but rarely do, especially when design evolves quickly.

What could we do better?

From experience, here’s what helps:

  • Agree on contract principles early
    Don’t treat string enums as strictly closed sets unless you must.
 Document them as extensible and ensure consumers know they must tolerate unknown values.


  • Separate reference data
    Expose a versioned endpoint for the list of valid titles, e.g. /api/v1/reference/titles
. Keep the API contract flexible (e.g. type “string”) but validate against reference data on the server side.


  • Domain events
    Consider events that flow through new values, so that the system accepts them without rigid coupling.
 For example, “CustomerTitleChanged” with an open string value, but checked downstream.


  • Governance conversations up front
    At project start, explicitly agree how enumerations will evolve and how clients must handle changes.
 This avoids Slack firefights months later when “simple” business changes come up.


The takeaway

This tiny story about “Dr” and “Prof” illustrates the bigger API vs data tension perfectly: Data wants to stay flexible; APIs want to stay stable
; Clients want predictability
. The only way to reconcile these is to design for change up front — not as an afterthought.

Closing

I hope this gave you food for thought about API design trade-offs. If you’d like to share your own experiences or thoughts, feel free to connect with me on LinkedIn or email me at mike@myglassesaredirty.com.