Ważne zmiany są złe!  Wersjonowanie API jest dobre!

Każdy, kto zbudował lub regularnie korzysta z API, prędzej czy później zdaje sobie sprawę, że ważne zmiany są bardzo złe i mogą stanowić poważny problem w wypadku innego przydatnego API. Ważna zmiana to zmiana w zachowaniu API, która może przerwać integrację użytkownika i prowadzić do wielu frustracji oraz utraty zaufania między dostawcą API a użytkownikiem. Ważne zmiany wymagają, aby użytkownicy byli powiadamiani z wyprzedzeniem (z towarzyszącymi przeprosinami), a nie gdy zmiana pojawia się bez zapowiedzi, jak na przykład miła nowa funkcja. Sposobem na uniknięcie tej frustracji jest wersjonowanie API z zapewnieniami od właściciela API, że nie wprowadzi zaskakujących zmian w ramach jednej wersji.

Jak trudno jest wersjonować API? Prawda jest taka, że nie jest to trudne, ale trudne jest utrzymanie pewnej zdrowego rozsądku, aby nie zafundować sobie niepotrzebnie oszałamiającej liczby wersji i podwersji stosowanych w dziesiątkach punktów końcowych API z niejasnymi zgodnościami.

Wprowadziliśmy wersję 1 API trzy lata temu i nie zdawaliśmy sobie sprawy, że będzie ona tak popularna do dziś. Jak więc udało nam się zapewnić najlepsze API dostarczania e-maili przez ponad dwa lata, ale nadal utrzymywać tę samą wersję API? Chociaż istnieje wiele różnych opinii na temat tego, jak wersjonować REST API, mam nadzieję, że historia naszej skromnej, ale potężnej wersji 1 może pomóc w drodze do oświecenia w zakresie wersjonowania API.

REST jest najlepszy

API SparkPost pochodzi z czasów, gdy byliśmy Message Systems, zanim zaczęliśmy przygodę w chmurze. W tym czasie intensywnie przygotowywaliśmy się do beta uruchomienia Momentum 4. Była to duża aktualizacja do wersji 3.x, naszego wiodącego na rynku MTA on-premise. Momentum 4 zawierało zupełnie nowe interfejsy użytkownika, analitykę w czasie rzeczywistym, a co najważniejsze, nowe API webowe do iniekcji i generowania wiadomości, zarządzania szablonami oraz uzyskiwania metryk e-mailowych. Nasza wizja polegała na architekturze first API – gdzie nawet interfejs użytkownika miałby interakcję z punktami końcowymi API.

Jedną z najwcześniejszych i najlepszych decyzji, jakie podjęliśmy, było przyjęcie stylu RESTful. Od końca lat 2000. reprezentacyjny transfer stanu (REST) stał się standardem dla chmurowych API. Użycie HTTP i JSON ułatwia programistom integrację z naszym API, niezależnie od tego, jakiego języka programowania używają – PHP, Ruby, Java – nie muszą wiedzieć ani troszczyć się o naszą technologię.

Wybór architektury RESTful był łatwy. Wybór konwencji wersjonowania nie był tak łatwy. Na początku zdecydowaliśmy się nie wersjonować bety wcale. Jednak po kilku miesiącach beta trafiła w ręce kilku klientów, a my zaczęliśmy rozbudowywać naszą chmurę.   Czas na wersjonowanie. Oceniliśmy dwie konwencje wersjonowania. Pierwsza to umieszczenie wersji bezpośrednio w URI, a druga to użycie nagłówka Accept. Pierwsza opcja jest bardziej jednoznaczna i mniej skomplikowana, co jest łatwiejsze dla programistów.   Ponieważ uwielbiamy programistów, to był logiczny wybór.

Zarządzanie API

Po wyborze konwencji wersjonowania mieliśmy więcej pytań. Kiedy zwiększymy wersję? Co to jest ważna zmiana?   Czy zrewidujemy całe API czy tylko niektóre punkty końcowe? W SparkPost mamy wiele zespołów pracujących nad różnymi częściami naszego API. W ramach tych zespołów osoby pracują nad różnymi punktami końcowymi w różnych momentach. Dlatego bardzo ważne jest, aby nasze API było spójne we współpracy z przyjętymi konwencjami. To było większe niż wersjonowanie.

Ustanowiliśmy grupę zarządzającą, która obejmuje inżynierów reprezentujących każdy zespół, członka zespołu zarządzania produktami oraz naszego CTO. Ta grupa jest odpowiedzialna za ustalanie, dokumentowanie i egzekwowanie naszych konwencji API w całym zespole. Kanał Slack poświęcony zarządzaniu API również jest przydatny do ożywionych dyskusji na ten temat.

Grupa zarządzająca zidentyfikowała wiele sposobów, w jakie zmiany mogą być wprowadzane do API, które są korzystne dla użytkownika i nie stanowią ważnej zmiany. Należą do nich:

• Nowy zasób lub punkt końcowy API

• Nowy opcjonalny parametr

• Zmiana w niepublicznym punkcie końcowym API

• Nowy opcjonalny klucz w ciele POST JSON

• Nowy klucz zwracany w ciele odpowiedzi JSON

Z drugiej strony, ważna zmiana obejmowała wszystko, co mogło przerwać integrację użytkownika, takie jak:

• Nowy wymagany parametr

• Nowy wymagany klucz w ciałach POST

• Usunięcie istniejącego punktu końcowego

• Usunięcie istniejącej metody żądania dla punktu końcowego

• Substancjalnie różne wewnętrzne zachowanie wywołania API – na przykład zmiana domyślnego zachowania.

Wielka wersja 1.0

Podczas dokumentowania i omawiania tych konwencji, doszliśmy do wniosku, że w interesie wszystkich (łącznie z nami!) jest unikanie wprowadzania ważnych zmian w API, ponieważ zarządzanie wieloma wersjami wiąże się z dużym obciążeniem. Zdecydowaliśmy, że istnieje kilka rzeczy, które powinniśmy poprawić w naszym API, zanim zobowiążemy się do „wersji 1”.

Wysyłanie prostego e-maila wymagało zbyt dużo wysiłku.   Aby „utrzymać proste rzeczy proste”, zaktualizowaliśmy ciało POST, aby zapewnić, że zarówno proste, jak i złożone przypadki użycia są uwzględnione.   Nowy format był również bardziej odporny na przyszłość.   Po drugie, zajęliśmy się problemem z punktem końcowym metryk. Ten punkt końcowy używał parametru „group_by”, który zmieniał format ciała odpowiedzi GET tak, że pierwszy klucz był wartością parametru grupującego. To nie wydawało się bardzo RESTful, więc rozdzieliliśmy każdą grupę na osobny punkt końcowy. W końcu dokonaliśmy audytu każdego punktu końcowego i wprowadziliśmy drobne zmiany tutaj i tam, aby upewnić się, że odpowiadają standardom.

Dokumentacja

Ważne jest, aby mieć dokładną i użyteczną dokumentację API, aby unikać wprowadzania ważnych zmian, zarówno celowych, jak i niezamierzonych. Zdecydowaliśmy się w zastosować prostą dokumentację API wykorzystującą język Markdown zwany API Blueprint oraz zarządzać naszymi dokumentami w Githubie. Nasza społeczność przyczynia się do udoskonalania tego otwartego oprogramowania.   Utrzymujemy również niepubliczny zestaw dokumentów w Githubie dla wewnętrznych API i punktów końcowych.

Początkowo publikowaliśmy naszą dokumentację na Apiary, wspaniałym narzędziu do prototypowania i publikowania dokumentacji API. Jednak osadzenie Apiary w naszej stronie internetowej nie działa na urządzeniach mobilnych, więc obecnie używamy Jekyll do generowania statycznych dokumentów.   Nasze najnowsze dokumenty API SparkPost ładują się szybko i dobrze działają na urządzeniach mobilnych, co jest ważne dla programistów, którzy nie zawsze siedzą przed komputerem.

Oddzielanie wdrożenia od publikacji

Nauczyliśmy się wkrótce cennej sztuczki oddzielania wdrożenia od publikacji. W ten sposób możliwe jest częste wdrażanie zmian, gdy są gotowe, poprzez ciągłe dostarczanie i wdrażanie, ale nie zawsze ogłaszamy je publicznie ani dokumentujemy w tym samym czasie. Nie jest niczym niezwykłym, że wdrażamy nowy punkt końcowy API lub ulepszenie istniejącego punktu końcowego API i używamy go z poziomu interfejsu użytkownika lub narzędzi wewnętrznych, zanim publicznie to udokumentujemy i wsparcie dla niego. W ten sposób możemy wprowadzić kilka poprawek do użyteczności lub zgodności ze standardami, nie martwiąc się o wprowadzenie przerażających ważnych zmian. Gdy jesteśmy zadowoleni ze zmiany, dodajemy ją do naszej publicznej dokumentacji.

O nie!

Sprawiedliwie jest przyznać, że były czasy, kiedy nie spełnialiśmy naszych ideałów „brak ważnych zmian”, a te przypadki warto przemyśleć. Pewnego razu zdecydowaliśmy, że lepiej będzie dla użytkowników, jeśli określona właściwość domyślnie będzie ustawiona na prawda zamiast fałsz. Po wdrożeniu zmiany otrzymaliśmy wiele skarg od użytkowników, ponieważ zachowanie zmieniło się w sposób nieoczekiwany.   Cofnęliśmy zmianę i dodaliśmy ustawienie dla poziomu konta – znacznie bardziej przyjazne użytkownikowi podejście.

Okazjonalnie mamy pokusę wprowadzenia ważnych zmian jako wynik poprawek błędów. Jednak zdecydowaliśmy się nie zmieniać tych osobliwości, aby nie ryzykować uszkodzenia integracji klientów dla potrzeby zachowania spójności.

Są rzadkie przypadki, kiedy podjęliśmy poważną decyzję o wprowadzeniu ważnej zmiany – na przykład zaniechanie zasobów API lub metody – w interesie większej społeczności użytkowników i tylko po potwierdzeniu, że wpływ na użytkowników jest niewielki lub żaden. Na przykład świadomie zdecydowaliśmy się zmienić sposób odpowiedzi API Suppression, ale tylko po starannym rozważeniu korzyści i skutków dla społeczności oraz starannym poinformowaniu użytkowników o zmianie. Jednak nigdy nie wprowadzilibyśmy zmiany, która miałaby choćby zdalny potencjał do bezpośredniego wpływu na wysyłanie produkcyjnych e-maili użytkownika.