Wersjonowanie API

API Prynt ma jedną, bieżącą wersję, bez numeru w adresie. Zmienia się razem z wydaniami Prynt, które trafiają do wszystkich drukarni naraz. Ta strona opisuje, jakie zmiany mogą się pojawić i jak uprzedzamy o tych, które wymagają zmian w integracji.

Stabilność

Każda operacja w referencji ma oznaczenie stabilności i wersję Prynt, od której jest dostępna.

• Stabilna Operacja zmienia się wyłącznie w sposób niełamiący. Element, którego używa, możemy usunąć tylko po pełnej procedurze wycofania opisanej niżej. Operacja stabilna nie wraca do bety.
• Beta Operacja może się jeszcze zmienić w sposób łamiący, bez okresu wycofania. Dotyczy to też typów, pól i argumentów, których używają wyłącznie operacje beta: możemy je zmienić albo usunąć razem z całą operacją. Każda taka zmiana trafia do historii zmian API w wydaniu, które ją wprowadza. Możesz używać operacji beta na produkcji, jeśli śledzisz historię zmian. Element, którego używa także operacja stabilna, podlega zasadom operacji stabilnych.

Zmiany niełamiące

Te zmiany mogą pojawić się w każdym wydaniu, z wpisem w historii zmian:

• nowe operacje, typy, pola i opcjonalne argumenty;
• nowe opcjonalne pola w typach wejściowych;
• nowe wartości enumów;
• nowe sub-kody błędów;
• złagodzenie walidacji, np. dłuższy dopuszczalny tekst.

Żeby integracja je przetrwała:

• obsłuż nieznaną wartość enuma zamiast przerywać działanie, np. zapisz ją jako „inna”;
• obsłuż nieznany subCode według jego kategorii code;
• nie polegaj na treści message, kolejności błędów ani kolejności pól w odpowiedzi.

Nowe pola nie zmieniają Twoich odpowiedzi: GraphQL zwraca tylko to, o co zapytasz. Jeśli trzymasz u siebie kopię danych, wartości nowego pola starszych rekordów pobierz pełnym przejściem listy: dodanie pola nie przesuwa ich updatedAt (zobacz Paginacja, filtry i synchronizacja).

Zmiany łamiące

Zmiana łamiąca to m.in. usunięcie albo zmiana nazwy operacji, pola, argumentu lub wartości enuma, zmiana typu, nowe wymagane pole wejściowe albo zmiana zachowania, na którym integracja może polegać. Elementu stabilnego nie zmieniamy w miejscu: obok niego pojawia się nowy, a stary przechodzi zawsze tę samą procedurę wycofania:

1. Element dostaje oznaczenie @deprecated z powodem i zamiennikiem. Widać je w pobranym schemacie, w referencji (Przestarzałe) i w narzędziach, które z niego korzystają, np. w generatorze typów.
2. Wydanie Prynt, które wprowadza oznaczenie, ma w historii zmian wpis o wycofaniu z najwcześniejszą datą usunięcia.
3. Element zostaje usunięty najwcześniej po 6 miesiącach kalendarzowych od dnia wydania, które przyniosło najnowszy wpis o jego wycofaniu. Cofnięcie wycofania anuluje ten termin, a ponowne wycofanie liczy 6 miesięcy od nowa. Usunięcie także trafia do historii zmian.

Jak śledzić zmiany

• Zaglądaj do historii zmian API przy każdym wydaniu Prynt.
• Trzymaj pobrany schemat w repozytorium integracji i porównuj go z nowym: różnica pokaże każdą zmianę.
• Uruchom generator typów na nowym schemacie: wskaże zapytania, które używają pól przestarzałych lub usuniętych.