Zmiany w API a stare wersje aplikacji mobilnej — jak rozwijać backend, nie psując aplikacji użytkownikom

Zmiana nazwy pola w API to dla strony www pięć minut, a dla aplikacji mobilnej — awarie u użytkowników starszych wersji. Które zmiany są niebezpieczne, jak rozszerzać API zamiast je zmieniać, kiedy wersjonować i jak testować zgodność.

Zespół Mobilesoft· Engineering team· 17 listopada 2026· 7 min czytania

Zespół backendowy zmienia nazwę pola w odpowiedzi API, aktualizuje panel webowy, testy przechodzą, wdrożenie trwa pięć minut. Następnego dnia w Crashlytics pojawia się fala awarii, a w sklepie jednogwiazdkowe opinie. Winna jest aplikacja mobilna w wersji sprzed roku, której część użytkowników nigdy nie zaktualizowała.

To jeden z najczęstszych problemów, z którymi zgłaszają się do nas firmy utrzymujące aplikacje. Poniżej opisujemy, dlaczego aplikacja mobilna wymaga innego podejścia do zmian w API niż strona internetowa, które zmiany psują stare wersje i jak rozwijać backend, nie zostawiając użytkowników z niedziałającą aplikacją.

Dlaczego aplikacja mobilna to inny klient niż strona www

Aplikacja webowa Aplikacja mobilna Wersja u użytkownika Zawsze najnowsza po odświeżeniu strony Ta, którą zainstalował — czasem sprzed kilku lat Czas wdrożenia poprawki Minuty Od kilku godzin do kilku dni (weryfikacja w sklepie, stopniowe udostępnianie) Wycofanie wadliwej wersji Natychmiastowe Niemożliwe dla tych, którzy już ją pobrali Kontrola nad aktualizacją Pełna Żadna, chyba że aplikacja ma mechanizm wymuszenia aktualizacji

Do tego dochodzi stopniowe udostępnianie: w Google Play nową wersję wypuszcza się zwykle procentowo, a w App Store fazowe wydanie rozkłada się na siedem dni. Nawet w najlepszym scenariuszu przez wiele dni działają równolegle co najmniej dwie wersje aplikacji, a w praktyce — kilkanaście.

Wniosek: backend aplikacji mobilnej musi obsługiwać nie jednego klienta, ale wszystkie wersje aplikacji, które wciąż są w użyciu.

Jakie zmiany psują stare wersje aplikacji

Nie każda zmiana w API jest niebezpieczna. Problem w tym, że część zmian wyglądających na bezpieczne psuje aplikacje — zależnie od tego, jak napisano parsowanie odpowiedzi.

Zmiana w API Ryzyko dla starej wersji Usunięcie lub zmiana nazwy pola Wysokie — brak danych albo awaria Zmiana typu pola (np. liczba na tekst) Wysokie — błąd parsowania całej odpowiedzi null w polu, które wcześniej zawsze miało wartość Wysokie, szczególnie w Kotlinie i Swifcie z typami nienullowalnymi Nowa wartość w polu typu enum (np. nowy status zamówienia) Wysokie przy domyślnej konfiguracji wielu bibliotek Nowy wymagany parametr w żądaniu Wysokie — stara wersja go nie wyśle Zmiana formatu daty, waluty, kodów błędów lub statusów HTTP Średnie do wysokiego Zmiana sposobu paginacji albo sortowania Średnie — błędne lub niepełne listy Dodanie nowego, opcjonalnego pola w odpowiedzi Zwykle niskie — ale nie zawsze Dodanie nowego endpointu Brak

Dwa przykłady, które regularnie spotykamy w przejmowanych projektach:

  • Nieznane pola. Biblioteka kotlinx.serialization w domyślnej konfiguracji zgłasza błąd, gdy w odpowiedzi pojawi się pole, którego nie zna klasa w aplikacji. Wystarczy, że backend doda nowe pole, a stara wersja aplikacji na Androidzie przestaje wczytywać ekran. Rozwiązaniem jest ustawienie ignoreUnknownKeys = true — ale tylko w nowych wersjach, stare zostaną z tym, co mają.
  • Nieznane wartości enum. Codable w Swifcie i domyślnie generowany kod json_serializable we Flutterze zgłaszają błąd, gdy w polu enum przyjdzie wartość spoza listy. Nowy status zamówienia dodany na backendzie potrafi wyłączyć ekran historii zamówień we wszystkich starszych wersjach aplikacji.

Dlatego zanim uznasz zmianę za bezpieczną, sprawdź, jak parsuje odpowiedzi najstarsza wersja aplikacji, która wciąż ma użytkowników.

Zasada: rozszerzaj, nie zmieniaj

Większość zmian da się przeprowadzić bez wersjonowania API, w modelu „rozszerz, przenieś, usuń” (w literaturze często expand and contract):

  1. Rozszerz. Dodaj nowe pole obok starego. Backend wypełnia oba, stare wersje aplikacji nadal korzystają ze starego.
  2. Przenieś. Wydaj wersję aplikacji, która korzysta z nowego pola.
  3. Poczekaj na dane. Obserwuj, ile żądań przychodzi ze starych wersji. O tym, skąd brać takie liczby, pisaliśmy w tekście o analityce aplikacji mobilnej.
  4. Usuń. Gdy udział starych wersji spadnie do akceptowalnego poziomu — albo po podniesieniu minimalnej wspieranej wersji — usuń stare pole.

Ten proces trwa tygodnie lub miesiące, a nie godziny. To normalne. Koszt utrzymywania dwóch pól przez kwartał jest znikomy w porównaniu z kosztem awarii u części użytkowników.

Wersjonowanie API — kiedy jest potrzebne

Gdy zmiana jest zbyt duża, żeby przeprowadzić ją przez rozszerzanie — nowy model danych, inny sposób autoryzacji, przebudowa całego procesu — potrzebna jest nowa wersja API.

Sposób Zalety Wady Wersja w ścieżce (/v1/orders, /v2/orders) Czytelne, łatwe do monitorowania i routowania Pokusa kopiowania całego API przy każdej zmianie Wersja w nagłówku Czyste adresy, wersja per żądanie Trudniejsze debugowanie i cache Rozgałęzienie po wersji aplikacji Bez zmian w adresach Logika warunkowa rozsiana po backendzie, trudna do usunięcia

Dla większości aplikacji, które utrzymujemy, sprawdza się połączenie: rozszerzanie przy codziennych zmianach i wersja w ścieżce przy dużych przebudowach. Warto też przyjąć zasadę, że równolegle działają najwyżej dwie wersje API, a starsza ma z góry ustaloną datę wyłączenia. Każda dodatkowa wersja to kod, który trzeba testować, zabezpieczać i aktualizować — o tym, ile kosztuje backend bez opieki, piszemy w artykule o utrzymaniu serwera aplikacji mobilnej.

Aplikacja musi mówić, w jakiej jest wersji

Wszystkie powyższe techniki wymagają jednego: backend musi wiedzieć, która wersja aplikacji wysłała żądanie. Najprostszy sposób to stały nagłówek z wersją i platformą, np. X-App-Version: 4.2.1 i X-Platform: ios, wysyłany w każdym żądaniu.

Dzięki temu:

  • w logach widać, ile ruchu generują poszczególne wersje,
  • backend może w wyjątkowych sytuacjach odpowiedzieć inaczej starszej wersji,
  • można bezpiecznie zdecydować, kiedy usunąć stare pole lub wyłączyć starą wersję API.

Drugim elementem jest mechanizm minimalnej wspieranej wersji — endpoint lub zdalna konfiguracja, która pozwala wymusić aktualizację, gdy utrzymanie zgodności przestaje mieć sens. Opisaliśmy go szczegółowo w tekście o wymuszaniu aktualizacji aplikacji. Oba mechanizmy trzeba dodać zawczasu: wersji, która już jest na telefonach, nie da się nauczyć wysyłania nagłówka.

Defensywny klient: jak pisać aplikację, żeby przetrwała zmiany

Część odporności leży po stronie aplikacji. W nowych wersjach warto zadbać o to, żeby:

  • ignorowała nieznane pola w odpowiedziach,
  • miała wartość domyślną dla nieznanych wartości enum (np. unknown) i wyświetlała je neutralnie, zamiast zgłaszać błąd,
  • traktowała brak opcjonalnych danych jako normalny stan, a nie wyjątek,
  • obsługiwała ustalone kody odpowiedzi — np. 410 Gone dla wycofanego endpointu — komunikatem z prośbą o aktualizację zamiast pustego ekranu,
  • nie wywoływała bezpośrednio zewnętrznych API, jeśli da się to zrobić przez własny backend. Gdy dostawca map, płatności czy logowania wycofa starą wersję API, poprawka po stronie serwera dotrze do wszystkich użytkowników naraz. O tym, jak często to się zdarza, piszemy w tekście o wycofanych SDK i API.

Testy zgodności

Ręczne sprawdzanie każdej zmiany na kilku starych wersjach aplikacji nie skaluje się. Lepiej zautomatyzować to po stronie backendu:

  • zapisane żądania i odpowiedzi starych wersji — zestaw przykładów, które przy każdej zmianie przechodzą przez nowy backend i są porównywane z oczekiwanym formatem,
  • testy kontraktowe (np. Pact) — aplikacja deklaruje, czego oczekuje od API, a backend nie może zostać wdrożony, jeśli łamie kontrakt którejkolwiek wspieranej wersji,
  • test na prawdziwej starej wersji przed większymi zmianami — zainstalowanie ostatnich wersji ze sklepu na urządzeniu testowym i przejście kluczowych ścieżek.

Jeśli aplikacja nie ma dziś żadnych testów, od czego zacząć, opisaliśmy w artykule o testach w starej aplikacji mobilnej.

Najczęstsze błędy

  • Wdrażanie zmian w API z myślą tylko o aplikacji webowej albo najnowszej wersji mobilnej.
  • Brak informacji o wersji aplikacji w żądaniach — decyzje o usunięciu pól zapadają w ciemno.
  • Nowa wersja API dla każdej zmiany, bez daty wyłączenia poprzednich.
  • Usunięcie starego pola zaraz po wydaniu nowej wersji aplikacji, zanim użytkownicy ją zainstalują.
  • Bezpośrednie wywołania zewnętrznych API z aplikacji, których nie da się poprawić bez aktualizacji.
  • Brak mechanizmu wymuszenia aktualizacji — jedynym wyjściem z niezgodności zostaje utrzymywanie starego API w nieskończoność.

Ile to kosztuje

Dodanie nagłówka z wersją aplikacji, mechanizmu minimalnej wersji, defensywnego parsowania w aplikacji i podstawowych testów zgodności dla kluczowych endpointów to zwykle 24–60 godzin pracy po stronie aplikacji i backendu. Przy przykładowej stawce 180 zł netto za godzinę daje to ok. 4,3–10,8 tys. zł netto. Stawka i zakres są orientacyjne — zależą od liczby endpointów i stanu kodu.

Dla porównania: jedna niezgodna zmiana w API, która wyłączy kluczowy ekran w starszych wersjach, to zwykle kilka dni gaszenia pożaru, pilne wydanie i spadek ocen w sklepie, który odrabia się miesiącami.

Podsumowanie

Aplikacja mobilna to klient, którego nie da się zaktualizować na życzenie. Backend musi obsługiwać wszystkie wersje, które wciąż są w użyciu. Większość zmian da się przeprowadzić przez rozszerzanie API: nowe pole obok starego, nowa wersja aplikacji, usunięcie starego pola dopiero po sprawdzeniu danych. Wersjonowanie zostaw na duże przebudowy i ogranicz do dwóch równoległych wersji. Fundamentem jest aplikacja, która wysyła swoją wersję, ma mechanizm minimalnej wspieranej wersji i nie wysypuje się na nieznanych danych.

Projektujemy i utrzymujemy backendy dla aplikacji mobilnych w ramach usługi backend i API, a zgodność aplikacji ze zmianami po stronie serwera pilnujemy w ramach utrzymania aplikacji mobilnych. Jeśli chcesz sprawdzić, jak Twoja aplikacja zniesie zmiany w API, zamów bezpłatną analizę aplikacji albo skontaktuj się z nami.