What I Learned Building Backend Features Used Across Multiple Clients

Gabriela Colombo — Mon, 05 Oct 2026 13:33:33 +0000

When engineers are early in their careers, we often think that if an API is correct, tested, and returns the expected response, the feature is ready.

Working on production systems used by different clients changed this perspective.

Backend changes rarely exist in isolation; the same API can be consumed by web, mobile apps, internal servers, etc. This means a backend change can be technically correct and still break the product if it’s not well planned.

Over the years, I learned to think beyond the endpoint/query/mutation itself. Before any changes to an API, I like to ask, “Who consumes this data today?” “How can this be backward compatible so as not to break anything in production?”

1. Your API Contract Is Bigger Than the Endpoint

An API contract isn't just the route, request body, and response documented in the specification.

Clients can depend on details that may look insignificant from the backend perspective.

For example, imagine an API returning:

{
  "id": "123",
  "role": "speaker"
}

A new requirement allows a user to have multiple roles. From a data-model perspective, changing the response to this might seem natural:

{
  "id": "123",
  "roles": ["speaker", "moderator"]
}

The new model may be better, but replacing role with roles immediately creates a breaking change.

The web application may already support the new model while an older mobile version still expects role.

The backend therefore has to consider not only what the ideal API should look like, but how clients will transition to it.

2. Backward compatibility is part of feature development

Deploying a breaking change to production can affect existing clients and users. For that reason, backward compatibility should be considered during development rather than after the feature is ready to be released.

Depending on the situation, one approach is to introduce new data as optional first and migrate existing records before making it mandatory.

One example I would like to share comes from a feature I developed around speaker roles. The new requirement was that every speaker should have a role assigned, which meant introducing information that would eventually become mandatory.

Making it mandatory immediately, however, would create a problem: thousands of existing speakers had been created before this requirement existed. The new feature had to support them as well.

Instead of assuming that the new requirement could be applied immediately, I treated the change as a transition.

First, the new role information was introduced without requiring it for existing data. This allowed the new backend behavior to coexist with records created under the previous model.

Next, I migrated the existing data. Speakers who already existed in the system needed to receive the appropriate default role so that, after the migration, both old and newly created records followed the same business rules.

Only after the existing data had been migrated could the new requirement safely be treated as mandatory.

Conceptually, the transition looked like this:

Old state:
Existing speakers → no explicit role required

Transition:
New role capability → optional → existing data migrated

New state:
All speakers → role guaranteed

This is an important distinction when developing features for systems already in production. A new business rule does not automatically mean that the existing data satisfies that rule.

The backend needs to provide a safe path between the old and new states.

In this case, backward compatibility was not only about keeping an API response unchanged. It also meant ensuring that existing data remained valid while the product transitioned to a new requirement.

3. Database redesigns need a transition state

The database model can evolve without requiring the API contract to change in the same way.

I faced this when a feature that originally supported a single role per speaker evolved to support multiple roles. The original data model was designed around a single relationship (1:1), but the new requirement needed a many-to-many relationship (1:N).

Instead of replacing the old model immediately, I introduced a new relationship model and treated the change as a transition.

During this transition, the API temporarily had to support both persistence models. When data was created or updated, the backend wrote the relevant information to both the legacy model and the new relationship model.

Conceptually, the flow looked like this:

Phase 1 — Introduce the new model

The new relationship was added while the existing model remained in production.

Phase 2 — Dual write

The backend temporarily persisted the relevant information in both models. This allowed new data to remain consistent while existing data was being migrated.

Phase 3 — Migrate existing data

Existing records were migrated to the new relationship model. During this process, both old and newly created data could continue to work without stopping the application.

Phase 4 — Switch to the new model

Once the migration was complete and the new model contained the expected data, the application could rely on the new relationship.

Phase 5 — Remove the legacy path

The temporary logic that wrote to the old model was removed. Once the application no longer depended on the legacy data, the old database structure could also be safely removed.

The important part was that the database change and the application change could not be treated as a single deployment.

For a period of time, the backend had to understand two representations of the same business concept and keep them consistent.

This approach added temporary complexity to the code, but that complexity had a purpose: it created a safe transition between two data models without requiring the production system to move from one state to another instantly.

It also changed how I think about database redesigns. Sometimes the safest solution is not to replace the old model immediately, but to design an intermediate state where both models can coexist until the migration is complete.

4. ”Nobody uses this field anymore” is a dangerous assumption

Removing legacy code is an important part of evolving a system. However, assuming that something is no longer used just because we cannot find an obvious reference to it can be dangerous.

Searching the codebase is a good starting point, but it doesn’t always show the whole picture. An API can have different consumers, older clients can still be running, and some code paths may only be executed under specific conditions.

Observability can help answer these questions.

For example, before removing an old behavior, we can add temporary logs or metrics around its usage and observe it for a period of time. Instead of assuming that a legacy path is no longer used, we can measure whether it is still being executed.

A removal process can look like:

Identify the legacy behavior → find known consumers → instrument its usage → observe → remove → monitor

This is especially useful during migrations. After moving to a new data model, I don’t want to remove the old path simply because the migration has finished. I also want to know that the application is no longer depending on it.

The goal is to turn “I think nobody uses this anymore” into “we have evidence that this is no longer being used.”

5. Observability after deployment

During development, I try to think about what information I will need after the feature reaches production. This means creating consistent logs around important operations, failures, unexpected states, etc.

Once the feature is deployed, these logs can be observed through tools such as Grafana or other monitoring platforms.

For a migration or a gradual rollout, for example, I want to understand:

if the new code path is being executed as expected
if some records cannot be processed by the new logic
if errors increased after the deployment
if the system reached a state that I didn’t expect during development
The important part is to think about observability before something goes wrong.

A log such as Something went wrong might tell me that an error happened, but it gives me very little information to investigate it. Good logs should provide enough context to understand which operation failed and at which point in the flow, without exposing sensitive information.

This becomes even more important when releasing changes incrementally. If old and new behaviors temporarily coexist, observability helps validate whether the transition is actually happening as expected.

For me, production is the final validation environment. Tests can validate the scenarios we know about, while observability helps us discover the scenarios we didn’t anticipate.

Conclusion

Building backend features for production systems taught me that implementing the expected behavior is only part of the job.

A backend engineer also needs to think about existing data, different consumers, migrations, backward compatibility, safe transitions, and how the system will be observed after deployment.

The question is no longer only:

“Does the new feature work?”

It also becomes:

“Can the system safely move from its current state to the new one?”

That change in perspective has influenced how I design features today. I try to think not only about the final architecture, but also about the path the system needs to take to get there.

Originally published on Medium