---
title: "API Versioning and Backward Compatibility"
description: "A change that looks harmless — renaming one field — can take down an integration at a customer you did not know existed."
canonical: "https://interfase.sk/en/news/api-versioning-and-backward-compatibility"
lang: "en"
last_updated: "2026-11-11"
---

# API Versioning and Backward Compatibility

> A change that looks harmless — renaming one field — can take down an integration at a customer you did not know existed.

Published: 2026-11-11

- Adding a field is safe, renaming or removing one is not — the difference is who feels the change and when.
- Without a list of who uses the API, nothing can be changed responsibly.
- Introduce a new version only when the change cannot be avoided; every extra version is a cost for years ahead.
- A mobile app cannot be forced to update — old API versions have to run longer than is comfortable.

A developer renames the field `zakaznik_id` to `customer_id`, because it is more consistent. Tests pass, it ships. Two days later a customer calls to say their order transfer has stopped working — the integration was built by an external supplier three years ago and nobody knew about it.

That is the whole subject of API versioning in one paragraph: **the problem is not the change, it is that somebody does not know about it.**

## Which changes are safe

The split is simpler than it looks.

**Safe** (nothing breaks):

- adding a new field to a response,
- adding an **optional** parameter,
- adding a new operation,
- extending an enumeration with a value — as long as consumers do not have to recognise it.

**Breaking** (need a new version):

- renaming or removing a field,
- changing a type (`"12"` to `12`, a number to text),
- adding a **required** parameter,
- changing the meaning of an existing field while keeping its name — the nastiest of all, because nothing crashes, the numbers just come out wrong,
- tightening validation that used to pass.

## The consumer you do not know about

Before anything can be changed responsibly, you need to know **who calls the API**. Not by guesswork but from records: which key, which operation, how often, when last.

That overview has two effects. It surfaces integrations everyone forgot about — and it surfaces the ones nobody has used for years, which can be switched off.

## Version, but sparingly

Every version you launch stays with you for years. So the first question is always: **can the change be avoided?** Often it can — a new field alongside the old one, the old one kept and marked as deprecated.

When it cannot, the version belongs in the path (`/v1/`, `/v2/`). It is the most legible option and can be read straight from a log with no further context.

And one rule that saves the most pain: **do not run more than two versions at once.** Three means every fix gets made three times.

## Retiring a version is a process, not an announcement

Switching a version off has an order worth keeping to:

1. **An announcement with a date** — not "soon" but a specific day, ideally six months ahead.
2. **A warning inside the responses** of the old version, so a developer sees it without reading an email.
3. **Direct contact** with those still using it — you have the list from your records.
4. **A trial shutdown** for a few hours before the real one. It surfaces whoever did not reply but is still calling.
5. **The shutdown** itself, with a comprehensible error response rather than silent failure.

## A mobile app changes the rules

A web application ships and everyone has the new version. A mobile one does not — some users go months without updating and some never do.

It follows that **old API versions have to run considerably longer** than is comfortable, and that the app needs a way to tell a user it will not go further without an update. That has to be built before it is needed — otherwise the only option left is running the old version forever.

## Errors are part of the contract

Error formats get forgotten, and yet they are the part consumers rely on most. If the structure of an error response or its code changes, integrations stop being able to tell "retry" from "this will never work".

Rate limits belong to the contract just as much — and tightening them is a breaking change, even when nothing in the data moves.

## Documentation that does not drift

Hand-written API documentation goes stale within three months. The only thing that works long-term is **generating it from the definition** that also drives validation — then it cannot drift from what the API actually does.

This connects to what we describe in [connecting company systems through APIs](/blog/prepojenie-firemnych-systemov-cez-api-ako-automatizovat-vymenu-dat).

## Where to start

With two things you can do this week: **turn on call logging** with consumer identification, and **write down what the public contract is** — which fields and operations you promise not to change without notice. Everything after that is a decision rather than a surprise.

If you are building an API or dealing with existing integrations, [get in touch](/kontakt). We handle it as part of [custom development](/riesenia/vyvoj) — examples in our [case studies](/referencie).


---

Web version: https://interfase.sk/en/news/api-versioning-and-backward-compatibility
llms.txt: https://interfase.sk/llms.txt