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 aktualizacjiDo 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 odpowiedzinull 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.
Codablew Swifcie i domyślnie generowany kodjson_serializablewe 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):
- Rozszerz. Dodaj nowe pole obok starego. Backend wypełnia oba, stare wersje aplikacji nadal korzystają ze starego.
- Przenieś. Wydaj wersję aplikacji, która korzysta z nowego pola.
- 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.
- 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 Gonedla 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.