Najlepsze praktyki wersjonowania API RESTful: Dlaczego v1 jest numerem 1
Chris McFadden
24 maj 2017
1 min read
Najważniejsze informacje
Wersjonowanie API zapobiega zmianom, które łamią kompatybilność i utrzymuje zaufanie między dostawcami API a deweloperami.
Jasne konwencje wersjonowania pomagają uniknąć chaotycznej mieszanki wersji w punktach końcowych.
API zgodne z zasadami REST w połączeniu z prostymi, jednoznacznymi identyfikatorami wersji utrzymują integracje intuicyjne dla deweloperów.
Grupy zarządzające zapewniają spójność w zespołach, zapobiegając przypadkowym zmianom łamiącym kompatybilność.
Nie wszystkie zmiany wymagają nowej wersji — tylko te, które łamią istniejące integracje.
Dobra dokumentacja jest niezbędna, aby uniknąć zamieszania i zapobiec przypadkowym zmianom łamiącym kompatybilność.
Oddzielając wdrożenie od wydania, zespoły mogą bezpiecznie testować i udoskonalać punkty końcowe przed ich ogłoszeniem.
Kiedy zmiany łamiące kompatybilność są nieuniknione, muszą być starannie ocenione i przekazywane.
Podsumowanie pytań i odpowiedzi
Dlaczego wersjonowanie API jest ważne?
Zapobiega to nieoczekiwanym zmianom łamiącym dla deweloperów integrujących się z twoim API, chroni zaufanie i zapewnia długoterminową stabilność aplikacji, które polegają na konsekwentnym zachowaniu.
Czym są zmiany łamiące w API?
Każda modyfikacja, która zmienia sposób działania istniejących integracji — na przykład usunięcie punktów końcowych, zmiana wartości domyślnych, dodanie wymaganych pól lub modyfikacja formatów odpowiedzi.
Dlaczego SparkPost wybrał REST jako fundament dla swojego interfejsu API?
Użycie HTTP i JSON w REST ułatwia programistom w różnych językach (PHP, Ruby, Java itp.) integrację bez konieczności posiadania specjalistycznej wiedzy na temat systemów podstawowych.
Jak SparkPost zdecydował o swojej metodzie wersjonowania?
Ocenili wersjonowanie z nagłówkiem Accept w porównaniu do wersjonowania URI i wybrali wersjonowanie URI, ponieważ jest ono bardziej jednoznaczne, proste i bardziej przyjazne dla deweloperów.
Jaką rolę odgrywa grupa zarządzająca API?
Ustanawia standardy, egzekwuje konsekwencję i zapobiega zespołom wprowadzeniu zmian, które konfliktują z konwencjami lub łamią zgodność.
Jakie rodzaje zmian nie są uważane za łamiące?
Dodawanie nowych opcjonalnych parametrów, wprowadzanie nowych punktów końcowych, dodawanie nowych kluczy w ładunkach JSON lub zmiana niepublicznych punktów końcowych — cokolwiek, co nie zakłóca istniejącego zachowania.
Jakie zmiany są uważane za breaking?
Dodawanie wymaganych parametrów, usuwanie punktów końcowych, zmiana domyślnych zachowań, modyfikacja struktury odpowiedzi lub wprowadzanie wymaganych pól JSON.
Dlaczego dokładna dokumentacja jest niezbędna?
Zapobiega to niezamierzonemu wprowadzaniu zmian łamiących działanie, pomaga programistom zrozumieć zachowanie i zapewnia, że zespoły aktualizują API w sposób niezawodny. SparkPost używał Markdown (API Blueprint) i GitHub do utrzymania przejrzystości i otwartości.
Jakie są korzyści z oddzielenia wdrożenia od wydania?
Zespoły mogą ciągle wdrażać nowe punkty końcowe lub ulepszenia wewnętrznie, testować je w rzeczywistych przepływach pracy, doskonalić zachowania i publicznie wydawać dopiero po stabilizacji — unikając przedwczesnej i potencjalnie łamiącej ekspozycji.
Co się stanie, jeśli zmiana wprowadza konieczność wprowadzenia przełomowej zmiany?
Musisz być to rzadkie, uzasadnione wyraźnymi korzyściami, starannie ocenione pod kątem wpływu na użytkowników i dokładnie komunikowane. Przykład: dostosowanie API Suppression tylko po potwierdzeniu minimalnego efektu i powiadomieniu.
Jak trudno może być wersjonować API? Prawda jest taka, że to nie jest trudne, ale trudne jest zachowanie jakiejkolwiek zdrowej sytuacji, nie wdając się niepotrzebnie w oszałamiającą liczbę wersji i podwersji stosowanych w dziesiątkach punktów końcowych API o niejasnych zgodnościach.
Jak trudno może być wersjonować API? Prawda jest taka, że to nie jest trudne, ale trudne jest zachowanie jakiejkolwiek zdrowej sytuacji, nie wdając się niepotrzebnie w oszałamiającą liczbę wersji i podwersji stosowanych w dziesiątkach punktów końcowych API o niejasnych zgodnościach.
Jak trudno może być wersjonować API? Prawda jest taka, że to nie jest trudne, ale trudne jest zachowanie jakiejkolwiek zdrowej sytuacji, nie wdając się niepotrzebnie w oszałamiającą liczbę wersji i podwersji stosowanych w dziesiątkach punktów końcowych API o niejasnych zgodnościach.
Doh!
Sprawiedliwie jest przyznać, że były czasy, kiedy nie spełnialiśmy naszych ideałów dotyczących „braku zmian łamiących zasady” i warto się z nich uczyć. Pewnego razu zdecydowaliśmy, że lepiej będzie dla użytkowników, jeśli pewna właściwość domyślnie będzie miała wartość true zamiast false. Po wdrożeniu zmiany otrzymaliśmy kilka skarg od użytkowników, ponieważ zachowanie zmieniło się w sposób nieoczekiwany. Cofnęliśmy zmianę i dodaliśmy ustawienie na poziomie konta – z pewnością znacznie bardziej przyjazne użytkownikom podejście.
Okazjonalnie kusimy się, aby wprowadzać zmiany łamiące zasady w wyniku poprawek błędów. Zdecydowaliśmy jednak, aby zostawić te idiosynkrazje w spokoju, zamiast ryzykować złamanie integracji klientów dla zachowania spójności.
Istnieją rzadkie przypadki, w których podjęliśmy poważną decyzję o wprowadzeniu zmiany łamiącej zasady – takiej jak deprecjonowanie zasobu lub metody API – w interesie szerszej społeczności użytkowników i tylko po potwierdzeniu, że ma to niewielki lub żaden wpływ na użytkowników. Na przykład, świadomie podjęliśmy decyzję o zmianie zachowania odpowiedzi API Ograniczenia, ale tylko po starannym rozważeniu korzyści i skutków dla społeczności oraz starannym komunikowaniu zmiany naszym użytkownikom. Jednak nigdy nie wprowadzilibyśmy zmiany, która miałaby znikome prawdopodobieństwo bezpośredniego wpływu na wysyłanie produkcyjnych e-maili użytkowników.
Sprawiedliwie jest przyznać, że były czasy, kiedy nie spełnialiśmy naszych ideałów dotyczących „braku zmian łamiących zasady” i warto się z nich uczyć. Pewnego razu zdecydowaliśmy, że lepiej będzie dla użytkowników, jeśli pewna właściwość domyślnie będzie miała wartość true zamiast false. Po wdrożeniu zmiany otrzymaliśmy kilka skarg od użytkowników, ponieważ zachowanie zmieniło się w sposób nieoczekiwany. Cofnęliśmy zmianę i dodaliśmy ustawienie na poziomie konta – z pewnością znacznie bardziej przyjazne użytkownikom podejście.
Okazjonalnie kusimy się, aby wprowadzać zmiany łamiące zasady w wyniku poprawek błędów. Zdecydowaliśmy jednak, aby zostawić te idiosynkrazje w spokoju, zamiast ryzykować złamanie integracji klientów dla zachowania spójności.
Istnieją rzadkie przypadki, w których podjęliśmy poważną decyzję o wprowadzeniu zmiany łamiącej zasady – takiej jak deprecjonowanie zasobu lub metody API – w interesie szerszej społeczności użytkowników i tylko po potwierdzeniu, że ma to niewielki lub żaden wpływ na użytkowników. Na przykład, świadomie podjęliśmy decyzję o zmianie zachowania odpowiedzi API Ograniczenia, ale tylko po starannym rozważeniu korzyści i skutków dla społeczności oraz starannym komunikowaniu zmiany naszym użytkownikom. Jednak nigdy nie wprowadzilibyśmy zmiany, która miałaby znikome prawdopodobieństwo bezpośredniego wpływu na wysyłanie produkcyjnych e-maili użytkowników.
Sprawiedliwie jest przyznać, że były czasy, kiedy nie spełnialiśmy naszych ideałów dotyczących „braku zmian łamiących zasady” i warto się z nich uczyć. Pewnego razu zdecydowaliśmy, że lepiej będzie dla użytkowników, jeśli pewna właściwość domyślnie będzie miała wartość true zamiast false. Po wdrożeniu zmiany otrzymaliśmy kilka skarg od użytkowników, ponieważ zachowanie zmieniło się w sposób nieoczekiwany. Cofnęliśmy zmianę i dodaliśmy ustawienie na poziomie konta – z pewnością znacznie bardziej przyjazne użytkownikom podejście.
Okazjonalnie kusimy się, aby wprowadzać zmiany łamiące zasady w wyniku poprawek błędów. Zdecydowaliśmy jednak, aby zostawić te idiosynkrazje w spokoju, zamiast ryzykować złamanie integracji klientów dla zachowania spójności.
Istnieją rzadkie przypadki, w których podjęliśmy poważną decyzję o wprowadzeniu zmiany łamiącej zasady – takiej jak deprecjonowanie zasobu lub metody API – w interesie szerszej społeczności użytkowników i tylko po potwierdzeniu, że ma to niewielki lub żaden wpływ na użytkowników. Na przykład, świadomie podjęliśmy decyzję o zmianie zachowania odpowiedzi API Ograniczenia, ale tylko po starannym rozważeniu korzyści i skutków dla społeczności oraz starannym komunikowaniu zmiany naszym użytkownikom. Jednak nigdy nie wprowadzilibyśmy zmiany, która miałaby znikome prawdopodobieństwo bezpośredniego wpływu na wysyłanie produkcyjnych e-maili użytkowników.
Breaking Changes Złe! Wersjonowanie API Dobre!
Jak każdy, kto zbudował lub regularnie korzysta z API, z czasem zdaje sobie sprawę, zmiany wprowadzające problemy są bardzo złe i mogą być poważnym blematem w w przeciwnym razie użytecznym API. Zmiana, która wprowadza problemy, to zmiana w zachowaniu API, która może przerwać integrację użytkownika i spowodować wiele frustracji oraz utraty zaufania między dostawcą API a użytkownikiem. Zmiany wprowadzające problemy wymagają, aby użytkownicy byli powiadomieni z wyprzedzeniem (z towarzyszącymi przeprosinami) zamiast zmiany, która po prostu się pojawia, jak urocza nowa funkcja. Sposobem na uniknięcie tej frustracji jest wersjonowanie API z zapewnieniami ze strony właściciela API, że nie będą wprowadzone żadne niespodziewane zmiany w ramach danej wersji.
Jak trudne może być wersjonowanie API? Prawda jest taka, że to nie jest trudne, ale trudne jest utrzymanie pewnej zdrowej równowagi, aby nie popaść w bezsensowną liczbę wersji i podwersji stosowanych w setkach punktów końcowych API z niejasną kompatybilnością.
Wprowadziliśmy wersję 1 API trzy lata temu i nie zdawaliśmy sobie sprawy, że będzie ona nadal działać do dziś. Jak udało nam się nadal oferować najlepsze API do dostarczania e-maili przez ponad dwa lata, zachowując jednocześnie tę samą wersję API? Ta stabilność jest kluczowa dla deweloperów budujących aplikacje z API e-mailowymi w chmurze, gdzie niezawodność i spójność są najważniejsze. 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 poprowadzić Cię na drodze do oświecenia w zakresie wersjonowania API.
Jak każdy, kto zbudował lub regularnie korzysta z API, z czasem zdaje sobie sprawę, zmiany wprowadzające problemy są bardzo złe i mogą być poważnym blematem w w przeciwnym razie użytecznym API. Zmiana, która wprowadza problemy, to zmiana w zachowaniu API, która może przerwać integrację użytkownika i spowodować wiele frustracji oraz utraty zaufania między dostawcą API a użytkownikiem. Zmiany wprowadzające problemy wymagają, aby użytkownicy byli powiadomieni z wyprzedzeniem (z towarzyszącymi przeprosinami) zamiast zmiany, która po prostu się pojawia, jak urocza nowa funkcja. Sposobem na uniknięcie tej frustracji jest wersjonowanie API z zapewnieniami ze strony właściciela API, że nie będą wprowadzone żadne niespodziewane zmiany w ramach danej wersji.
Jak trudne może być wersjonowanie API? Prawda jest taka, że to nie jest trudne, ale trudne jest utrzymanie pewnej zdrowej równowagi, aby nie popaść w bezsensowną liczbę wersji i podwersji stosowanych w setkach punktów końcowych API z niejasną kompatybilnością.
Wprowadziliśmy wersję 1 API trzy lata temu i nie zdawaliśmy sobie sprawy, że będzie ona nadal działać do dziś. Jak udało nam się nadal oferować najlepsze API do dostarczania e-maili przez ponad dwa lata, zachowując jednocześnie tę samą wersję API? Ta stabilność jest kluczowa dla deweloperów budujących aplikacje z API e-mailowymi w chmurze, gdzie niezawodność i spójność są najważniejsze. 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 poprowadzić Cię na drodze do oświecenia w zakresie wersjonowania API.
Jak każdy, kto zbudował lub regularnie korzysta z API, z czasem zdaje sobie sprawę, zmiany wprowadzające problemy są bardzo złe i mogą być poważnym blematem w w przeciwnym razie użytecznym API. Zmiana, która wprowadza problemy, to zmiana w zachowaniu API, która może przerwać integrację użytkownika i spowodować wiele frustracji oraz utraty zaufania między dostawcą API a użytkownikiem. Zmiany wprowadzające problemy wymagają, aby użytkownicy byli powiadomieni z wyprzedzeniem (z towarzyszącymi przeprosinami) zamiast zmiany, która po prostu się pojawia, jak urocza nowa funkcja. Sposobem na uniknięcie tej frustracji jest wersjonowanie API z zapewnieniami ze strony właściciela API, że nie będą wprowadzone żadne niespodziewane zmiany w ramach danej wersji.
Jak trudne może być wersjonowanie API? Prawda jest taka, że to nie jest trudne, ale trudne jest utrzymanie pewnej zdrowej równowagi, aby nie popaść w bezsensowną liczbę wersji i podwersji stosowanych w setkach punktów końcowych API z niejasną kompatybilnością.
Wprowadziliśmy wersję 1 API trzy lata temu i nie zdawaliśmy sobie sprawy, że będzie ona nadal działać do dziś. Jak udało nam się nadal oferować najlepsze API do dostarczania e-maili przez ponad dwa lata, zachowując jednocześnie tę samą wersję API? Ta stabilność jest kluczowa dla deweloperów budujących aplikacje z API e-mailowymi w chmurze, gdzie niezawodność i spójność są najważniejsze. 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 poprowadzić Cię na 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 nasze przygody w chmurze. Wtedy zajmowaliśmy się ostatnimi przygotowaniami do beta uruchomienia Momentum 4. To był główny upgrade do wersji 3.x, naszego wiodącego na rynku lokalnego MTA. Momentum 4 zawierał całkowicie nowy interfejs użytkownika, analitykę w czasie rzeczywistym, a co najważniejsze, nowy interfejs API do wstrzykiwania i generowania wiadomości, zarządzania szablonami i uzyskiwania metryk e-mailowych. Nasza wizja to architektura oparta na API – gdzie nawet UI będzie interagować 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-tych transfer stanu reprezentacyjnego (REST) bazowe interfejsy API w sieci stały się de facto standardem interfejsów API w chmurze. Użycie HTTP i JSON sprawia, że łatwo jest programistom, niezależnie od tego, w jakim języku programowania się posługują – PHP, Ruby i Java – integrować się z naszym API bez potrzeby znajomości lub troski o naszą technologię bazową. Jednak budowanie API natywnych dla chmury na dużą skalę może stawić czoła niespodziewanym wyzwaniom infrastrukturalnym, takim jak limity skalowania DNS, które napotkaliśmy w AWS, obsługując duży ruch API.
Wybór architektury RESTful był łatwy. Wybór konwencji wersjonowania nie był tak prosty. Początkowo zrezygnowaliśmy z pytania o wersjonowanie, nie wersjonując bety wcale. Jednak w ciągu kilku miesięcy beta trafiła do rąk kilku klientów i zaczęliśmy rozwijać naszą usługę chmurową. Czas na wersjonowanie. Oceniliśmy dwie konwencje wersjonowania.
Podejście do wersjonowania | Jak to działa | Wymiana |
|---|---|---|
Wersjonowanie URI | Wersja zawarta w ścieżce punktu końcowego | Jasne i łatwe do zrozumienia |
Wersjonowanie nagłówka Accept | Wersja przekazywana przez nagłówek HTTP | Mniej widoczna, bardziej skomplikowana dla programistów |
Pierwszym było wprowadzenie wersjonowania bezpośrednio w URI, a drugim użycie nagłówka Accept. Pierwsza opcja jest bardziej wyraźna i mniej skomplikowana, co ułatwia pracę programistom. Ponieważ uwielbiamy programistów, to był logiczny wybór.
API SparkPost pochodzi z czasów, gdy byliśmy Message Systems, zanim zaczęliśmy nasze przygody w chmurze. Wtedy zajmowaliśmy się ostatnimi przygotowaniami do beta uruchomienia Momentum 4. To był główny upgrade do wersji 3.x, naszego wiodącego na rynku lokalnego MTA. Momentum 4 zawierał całkowicie nowy interfejs użytkownika, analitykę w czasie rzeczywistym, a co najważniejsze, nowy interfejs API do wstrzykiwania i generowania wiadomości, zarządzania szablonami i uzyskiwania metryk e-mailowych. Nasza wizja to architektura oparta na API – gdzie nawet UI będzie interagować 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-tych transfer stanu reprezentacyjnego (REST) bazowe interfejsy API w sieci stały się de facto standardem interfejsów API w chmurze. Użycie HTTP i JSON sprawia, że łatwo jest programistom, niezależnie od tego, w jakim języku programowania się posługują – PHP, Ruby i Java – integrować się z naszym API bez potrzeby znajomości lub troski o naszą technologię bazową. Jednak budowanie API natywnych dla chmury na dużą skalę może stawić czoła niespodziewanym wyzwaniom infrastrukturalnym, takim jak limity skalowania DNS, które napotkaliśmy w AWS, obsługując duży ruch API.
Wybór architektury RESTful był łatwy. Wybór konwencji wersjonowania nie był tak prosty. Początkowo zrezygnowaliśmy z pytania o wersjonowanie, nie wersjonując bety wcale. Jednak w ciągu kilku miesięcy beta trafiła do rąk kilku klientów i zaczęliśmy rozwijać naszą usługę chmurową. Czas na wersjonowanie. Oceniliśmy dwie konwencje wersjonowania.
Podejście do wersjonowania | Jak to działa | Wymiana |
|---|---|---|
Wersjonowanie URI | Wersja zawarta w ścieżce punktu końcowego | Jasne i łatwe do zrozumienia |
Wersjonowanie nagłówka Accept | Wersja przekazywana przez nagłówek HTTP | Mniej widoczna, bardziej skomplikowana dla programistów |
Pierwszym było wprowadzenie wersjonowania bezpośrednio w URI, a drugim użycie nagłówka Accept. Pierwsza opcja jest bardziej wyraźna i mniej skomplikowana, co ułatwia pracę programistom. Ponieważ uwielbiamy programistów, to był logiczny wybór.
API SparkPost pochodzi z czasów, gdy byliśmy Message Systems, zanim zaczęliśmy nasze przygody w chmurze. Wtedy zajmowaliśmy się ostatnimi przygotowaniami do beta uruchomienia Momentum 4. To był główny upgrade do wersji 3.x, naszego wiodącego na rynku lokalnego MTA. Momentum 4 zawierał całkowicie nowy interfejs użytkownika, analitykę w czasie rzeczywistym, a co najważniejsze, nowy interfejs API do wstrzykiwania i generowania wiadomości, zarządzania szablonami i uzyskiwania metryk e-mailowych. Nasza wizja to architektura oparta na API – gdzie nawet UI będzie interagować 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-tych transfer stanu reprezentacyjnego (REST) bazowe interfejsy API w sieci stały się de facto standardem interfejsów API w chmurze. Użycie HTTP i JSON sprawia, że łatwo jest programistom, niezależnie od tego, w jakim języku programowania się posługują – PHP, Ruby i Java – integrować się z naszym API bez potrzeby znajomości lub troski o naszą technologię bazową. Jednak budowanie API natywnych dla chmury na dużą skalę może stawić czoła niespodziewanym wyzwaniom infrastrukturalnym, takim jak limity skalowania DNS, które napotkaliśmy w AWS, obsługując duży ruch API.
Wybór architektury RESTful był łatwy. Wybór konwencji wersjonowania nie był tak prosty. Początkowo zrezygnowaliśmy z pytania o wersjonowanie, nie wersjonując bety wcale. Jednak w ciągu kilku miesięcy beta trafiła do rąk kilku klientów i zaczęliśmy rozwijać naszą usługę chmurową. Czas na wersjonowanie. Oceniliśmy dwie konwencje wersjonowania.
Podejście do wersjonowania | Jak to działa | Wymiana |
|---|---|---|
Wersjonowanie URI | Wersja zawarta w ścieżce punktu końcowego | Jasne i łatwe do zrozumienia |
Wersjonowanie nagłówka Accept | Wersja przekazywana przez nagłówek HTTP | Mniej widoczna, bardziej skomplikowana dla programistów |
Pierwszym było wprowadzenie wersjonowania bezpośrednio w URI, a drugim użycie nagłówka Accept. Pierwsza opcja jest bardziej wyraźna i mniej skomplikowana, co ułatwia pracę programistom. Ponieważ uwielbiamy programistów, to był logiczny wybór.
Zarządzanie API
Z wybraną konwencją wersjonowania mieliśmy więcej pytań. Kiedy powinniśmy zwiększyć wersję? Co to jest zmiana łamiąca? Czy wrócimy do wersjonowania całego interfejsu API, czy tylko niektórych punktów końcowych? W SparkPost mamy wiele zespołów pracujących nad różnymi częściami naszego interfejsu API. W ramach tych zespołów ludzie pracują nad różnymi punktami końcowymi w różnych momentach. Dlatego tak ważne jest, aby nasz interfejs API był spójny w używaniu konwencji. To było większe niż wersjonowanie.
Ustanowiliśmy grupę zarządzającą, w której skład wchodzili inżynierowie reprezentujący każdy zespół, członek zespołu zarządzania produktami oraz nasz CTO. Grupa ta jest odpowiedzialna za ustanawianie, dokumentowanie i egzekwowanie naszych konwencji API w wszystkich zespołach. Kanał Slack do zarządzania API również okazuje się przydatny w ożywionych debatach na ten temat.
Grupa zarządzająca zidentyfikowała szereg sposobów, w jakie zmiany mogą być wprowadzane do interfejsu API, które są korzystne dla użytkownika i nie stanowią zmiany łamiącej.
Typ zmiany | Uważana za łamiącą? | Powód |
|---|---|---|
Nowy zasób lub punkt końcowy | Nie | Nie wpływa na istniejące integracje |
Nowy opcjonalny parametr | Nie | Istniejące żądania pozostają ważne |
Nowy opcjonalny klucz JSON | Nie | Klienci mogą bezpiecznie go zignorować |
Nowe pole odpowiedzi | Nie | Kompatybilne wstecznie dla odbiorców |
Nowy wymagany parametr | Tak | Łamie istniejące żądania |
Nowy wymagany klucz POST | Tak | Unieważnia istniejące ładunki |
Usunięcie punktu końcowego | Tak | Istniejące integracje przestają działać |
Zmiana domyślnego zachowania | Tak | Zmienia oczekiwane wyniki |
Wśród nich znajdują się:
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
Przeciwnie, zmiana łamiąca obejmowała wszystko, co mogło zniszczyć integrację użytkownika, takie jak:
Nowy wymagany parametr
Nowy wymagany klucz w ciałach POST
Usunięcie istniejącego punktu końcowego
Usunięcie metody żądania istniejącego punktu końcowego
Znacząco inne wewnętrzne zachowanie wywołania API – na przykład zmiana domyślnego zachowania.
Z wybraną konwencją wersjonowania mieliśmy więcej pytań. Kiedy powinniśmy zwiększyć wersję? Co to jest zmiana łamiąca? Czy wrócimy do wersjonowania całego interfejsu API, czy tylko niektórych punktów końcowych? W SparkPost mamy wiele zespołów pracujących nad różnymi częściami naszego interfejsu API. W ramach tych zespołów ludzie pracują nad różnymi punktami końcowymi w różnych momentach. Dlatego tak ważne jest, aby nasz interfejs API był spójny w używaniu konwencji. To było większe niż wersjonowanie.
Ustanowiliśmy grupę zarządzającą, w której skład wchodzili inżynierowie reprezentujący każdy zespół, członek zespołu zarządzania produktami oraz nasz CTO. Grupa ta jest odpowiedzialna za ustanawianie, dokumentowanie i egzekwowanie naszych konwencji API w wszystkich zespołach. Kanał Slack do zarządzania API również okazuje się przydatny w ożywionych debatach na ten temat.
Grupa zarządzająca zidentyfikowała szereg sposobów, w jakie zmiany mogą być wprowadzane do interfejsu API, które są korzystne dla użytkownika i nie stanowią zmiany łamiącej.
Typ zmiany | Uważana za łamiącą? | Powód |
|---|---|---|
Nowy zasób lub punkt końcowy | Nie | Nie wpływa na istniejące integracje |
Nowy opcjonalny parametr | Nie | Istniejące żądania pozostają ważne |
Nowy opcjonalny klucz JSON | Nie | Klienci mogą bezpiecznie go zignorować |
Nowe pole odpowiedzi | Nie | Kompatybilne wstecznie dla odbiorców |
Nowy wymagany parametr | Tak | Łamie istniejące żądania |
Nowy wymagany klucz POST | Tak | Unieważnia istniejące ładunki |
Usunięcie punktu końcowego | Tak | Istniejące integracje przestają działać |
Zmiana domyślnego zachowania | Tak | Zmienia oczekiwane wyniki |
Wśród nich znajdują się:
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
Przeciwnie, zmiana łamiąca obejmowała wszystko, co mogło zniszczyć integrację użytkownika, takie jak:
Nowy wymagany parametr
Nowy wymagany klucz w ciałach POST
Usunięcie istniejącego punktu końcowego
Usunięcie metody żądania istniejącego punktu końcowego
Znacząco inne wewnętrzne zachowanie wywołania API – na przykład zmiana domyślnego zachowania.
Z wybraną konwencją wersjonowania mieliśmy więcej pytań. Kiedy powinniśmy zwiększyć wersję? Co to jest zmiana łamiąca? Czy wrócimy do wersjonowania całego interfejsu API, czy tylko niektórych punktów końcowych? W SparkPost mamy wiele zespołów pracujących nad różnymi częściami naszego interfejsu API. W ramach tych zespołów ludzie pracują nad różnymi punktami końcowymi w różnych momentach. Dlatego tak ważne jest, aby nasz interfejs API był spójny w używaniu konwencji. To było większe niż wersjonowanie.
Ustanowiliśmy grupę zarządzającą, w której skład wchodzili inżynierowie reprezentujący każdy zespół, członek zespołu zarządzania produktami oraz nasz CTO. Grupa ta jest odpowiedzialna za ustanawianie, dokumentowanie i egzekwowanie naszych konwencji API w wszystkich zespołach. Kanał Slack do zarządzania API również okazuje się przydatny w ożywionych debatach na ten temat.
Grupa zarządzająca zidentyfikowała szereg sposobów, w jakie zmiany mogą być wprowadzane do interfejsu API, które są korzystne dla użytkownika i nie stanowią zmiany łamiącej.
Typ zmiany | Uważana za łamiącą? | Powód |
|---|---|---|
Nowy zasób lub punkt końcowy | Nie | Nie wpływa na istniejące integracje |
Nowy opcjonalny parametr | Nie | Istniejące żądania pozostają ważne |
Nowy opcjonalny klucz JSON | Nie | Klienci mogą bezpiecznie go zignorować |
Nowe pole odpowiedzi | Nie | Kompatybilne wstecznie dla odbiorców |
Nowy wymagany parametr | Tak | Łamie istniejące żądania |
Nowy wymagany klucz POST | Tak | Unieważnia istniejące ładunki |
Usunięcie punktu końcowego | Tak | Istniejące integracje przestają działać |
Zmiana domyślnego zachowania | Tak | Zmienia oczekiwane wyniki |
Wśród nich znajdują się:
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
Przeciwnie, zmiana łamiąca obejmowała wszystko, co mogło zniszczyć integrację użytkownika, takie jak:
Nowy wymagany parametr
Nowy wymagany klucz w ciałach POST
Usunięcie istniejącego punktu końcowego
Usunięcie metody żądania istniejącego punktu końcowego
Znacząco inne wewnętrzne zachowanie wywołania API – na przykład zmiana domyślnego zachowania.
Wielki 1.0
Podczas gdy dokumentowaliśmy i omawialiśmy te konwencje, doszliśmy również do wniosku, że w interesie każdego (w tym naszym!) jest unikanie wprowadzania zmian łamiących API, ponieważ zarządzanie wieloma wersjami wiąże się z dużym nakładem pracy. Zdecydowaliśmy, że jest kilka rzeczy, które powinniśmy naprawić w naszym API przed zobowiązaniem się do "v1".
Wysłanie prostego e-maila wymagało zbyt wiele wysiłku. Aby "utrzymać proste rzeczy prosto", 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ł bardziej przyszłościowy. Po drugie, rozwiązaliśmy problem z końcówką Metrics. Ta końcówka używała parametru "group_by", który zmieniał format ciała odpowiedzi GET, aby pierwszym kluczem była wartość parametru grupowania. To nie wydawało się zbyt RESTful, więc podzieliliśmy każdą grupę na osobną końcówkę. Na koniec audytowaliśmy każdą końcówkę i wprowadziliśmy drobne zmiany tutaj i tam, aby zapewnić, że są zgodne ze standardami.
Podczas gdy dokumentowaliśmy i omawialiśmy te konwencje, doszliśmy również do wniosku, że w interesie każdego (w tym naszym!) jest unikanie wprowadzania zmian łamiących API, ponieważ zarządzanie wieloma wersjami wiąże się z dużym nakładem pracy. Zdecydowaliśmy, że jest kilka rzeczy, które powinniśmy naprawić w naszym API przed zobowiązaniem się do "v1".
Wysłanie prostego e-maila wymagało zbyt wiele wysiłku. Aby "utrzymać proste rzeczy prosto", 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ł bardziej przyszłościowy. Po drugie, rozwiązaliśmy problem z końcówką Metrics. Ta końcówka używała parametru "group_by", który zmieniał format ciała odpowiedzi GET, aby pierwszym kluczem była wartość parametru grupowania. To nie wydawało się zbyt RESTful, więc podzieliliśmy każdą grupę na osobną końcówkę. Na koniec audytowaliśmy każdą końcówkę i wprowadziliśmy drobne zmiany tutaj i tam, aby zapewnić, że są zgodne ze standardami.
Podczas gdy dokumentowaliśmy i omawialiśmy te konwencje, doszliśmy również do wniosku, że w interesie każdego (w tym naszym!) jest unikanie wprowadzania zmian łamiących API, ponieważ zarządzanie wieloma wersjami wiąże się z dużym nakładem pracy. Zdecydowaliśmy, że jest kilka rzeczy, które powinniśmy naprawić w naszym API przed zobowiązaniem się do "v1".
Wysłanie prostego e-maila wymagało zbyt wiele wysiłku. Aby "utrzymać proste rzeczy prosto", 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ł bardziej przyszłościowy. Po drugie, rozwiązaliśmy problem z końcówką Metrics. Ta końcówka używała parametru "group_by", który zmieniał format ciała odpowiedzi GET, aby pierwszym kluczem była wartość parametru grupowania. To nie wydawało się zbyt RESTful, więc podzieliliśmy każdą grupę na osobną końcówkę. Na koniec audytowaliśmy każdą końcówkę i wprowadziliśmy drobne zmiany tutaj i tam, aby zapewnić, że są zgodne ze standardami.
Dokładna dokumentacja
Ważne jest, aby mieć dokładną i użyteczną dokumentację API, aby uniknąć zmian, zarówno zamierzonych, jak i niezamierzonych. Zdecydowaliśmy się na prostą metodę dokumentacji API, wykorzystując język Markdown zwany API Blueprint oraz zarządzając naszą dokumentacją w Githubie. Nasza społeczność przyczynia się do poprawy i tworzenia tych dokumentów typu open source. Utrzymujemy także niepubliczny zestaw dokumentów w Githubie dla wewnętrznych API i punktów końcowych.
Początkowo publikowaliśmy nasze dokumenty na Apiary, świetnym narzędziu do prototypowania i publikacji dokumentacji API. Jednak osadzenie Apiary na naszej stronie internetowej nie działa na urządzeniach mobilnych, więc teraz używamy Jekyll, aby generować statyczną dokumentację. Nasza najnowsza dokumentacja API SparkPost ładuje się teraz szybko i dobrze działa na urządzeniach mobilnych, co jest ważne dla deweloperów, którzy nie zawsze siedzą przy swoim komputerze.
Ważne jest, aby mieć dokładną i użyteczną dokumentację API, aby uniknąć zmian, zarówno zamierzonych, jak i niezamierzonych. Zdecydowaliśmy się na prostą metodę dokumentacji API, wykorzystując język Markdown zwany API Blueprint oraz zarządzając naszą dokumentacją w Githubie. Nasza społeczność przyczynia się do poprawy i tworzenia tych dokumentów typu open source. Utrzymujemy także niepubliczny zestaw dokumentów w Githubie dla wewnętrznych API i punktów końcowych.
Początkowo publikowaliśmy nasze dokumenty na Apiary, świetnym narzędziu do prototypowania i publikacji dokumentacji API. Jednak osadzenie Apiary na naszej stronie internetowej nie działa na urządzeniach mobilnych, więc teraz używamy Jekyll, aby generować statyczną dokumentację. Nasza najnowsza dokumentacja API SparkPost ładuje się teraz szybko i dobrze działa na urządzeniach mobilnych, co jest ważne dla deweloperów, którzy nie zawsze siedzą przy swoim komputerze.
Ważne jest, aby mieć dokładną i użyteczną dokumentację API, aby uniknąć zmian, zarówno zamierzonych, jak i niezamierzonych. Zdecydowaliśmy się na prostą metodę dokumentacji API, wykorzystując język Markdown zwany API Blueprint oraz zarządzając naszą dokumentacją w Githubie. Nasza społeczność przyczynia się do poprawy i tworzenia tych dokumentów typu open source. Utrzymujemy także niepubliczny zestaw dokumentów w Githubie dla wewnętrznych API i punktów końcowych.
Początkowo publikowaliśmy nasze dokumenty na Apiary, świetnym narzędziu do prototypowania i publikacji dokumentacji API. Jednak osadzenie Apiary na naszej stronie internetowej nie działa na urządzeniach mobilnych, więc teraz używamy Jekyll, aby generować statyczną dokumentację. Nasza najnowsza dokumentacja API SparkPost ładuje się teraz szybko i dobrze działa na urządzeniach mobilnych, co jest ważne dla deweloperów, którzy nie zawsze siedzą przy swoim komputerze.
Separacja wdrożenia od wydania
Nauczyliśmy się wcześnie cennej sztuczki oddzielania wdrożenia od wydania. W ten sposób można często wprowadzać zmiany, gdy są gotowe, dzięki ciągłemu dostarczaniu i wdrażaniu, ale nie zawsze ogłaszamy lub dokumentujemy je publicznie w tym samym czasie. Nie jest niecodziennością wdrożenie nowego punktu końcowego API lub ulepszenia istniejącego punktu końcowego API i korzystanie z niego z poziomu UI lub za pomocą narzędzi wewnętrznych, zanim je publicznie udokumentujemy i wsparliśmy. Dzięki temu możemy wprowadzać pewne poprawki pod kątem użyteczności lub zgodności z normami, nie martwiąc się o wprowadzenie niechcianej zmiany łamiącej kompatybilność. Gdy będziemy zadowoleni ze zmiany, dodajemy ją do naszej publicznej dokumentacji.
Nauczyliśmy się wcześnie cennej sztuczki oddzielania wdrożenia od wydania. W ten sposób można często wprowadzać zmiany, gdy są gotowe, dzięki ciągłemu dostarczaniu i wdrażaniu, ale nie zawsze ogłaszamy lub dokumentujemy je publicznie w tym samym czasie. Nie jest niecodziennością wdrożenie nowego punktu końcowego API lub ulepszenia istniejącego punktu końcowego API i korzystanie z niego z poziomu UI lub za pomocą narzędzi wewnętrznych, zanim je publicznie udokumentujemy i wsparliśmy. Dzięki temu możemy wprowadzać pewne poprawki pod kątem użyteczności lub zgodności z normami, nie martwiąc się o wprowadzenie niechcianej zmiany łamiącej kompatybilność. Gdy będziemy zadowoleni ze zmiany, dodajemy ją do naszej publicznej dokumentacji.
Nauczyliśmy się wcześnie cennej sztuczki oddzielania wdrożenia od wydania. W ten sposób można często wprowadzać zmiany, gdy są gotowe, dzięki ciągłemu dostarczaniu i wdrażaniu, ale nie zawsze ogłaszamy lub dokumentujemy je publicznie w tym samym czasie. Nie jest niecodziennością wdrożenie nowego punktu końcowego API lub ulepszenia istniejącego punktu końcowego API i korzystanie z niego z poziomu UI lub za pomocą narzędzi wewnętrznych, zanim je publicznie udokumentujemy i wsparliśmy. Dzięki temu możemy wprowadzać pewne poprawki pod kątem użyteczności lub zgodności z normami, nie martwiąc się o wprowadzenie niechcianej zmiany łamiącej kompatybilność. Gdy będziemy zadowoleni ze zmiany, dodajemy ją do naszej publicznej dokumentacji.
