Zasady dla konstruktora interfejsu API danych
Zestaw zasad zarządza konstruktorem interfejsu API danych związanymi ze zmianami powodującymi niezgodność, powiadomieniami, wydaniami i przechowywaniem wersji.
Przechowywanie wersji i wydania
Wersja w kontekście konstruktora interfejsu API danych odnosi się do każdej opublikowanej wersji oprogramowania identyfikowanej przez Major.Minor.Patch format. Te wersje należą do trzech kategorii: stabilna, zmiana powodująca niezgodność i wersja zapoznawcza.
Stabilne wersje
Stabilna wersja konstruktora interfejsu API danych jest zgodna z poprzednimi wersjami. Zgodne z poprzednimi wersjami oznacza, że każdy kod, który jest oparty na jednej wersji konstruktora interfejsu API danych, może przyjąć nowszą stabilną wersję bez konieczności wprowadzania zmian kodu w celu zachowania poprawności lub istniejącej funkcjonalności.
Wydania zmian powodujących niezgodność
Niezgodna wersja konstruktora interfejsu API danych nie jest zgodna z poprzednimi wersjami. Wdrożenie wersji zmiany powodującej niezgodność w istniejącym kodzie klienta może wymagać zmian kodu, aby upewnić się, że klient zachowuje się dokładnie tak samo, jak w przypadku określania wartości docelowej poprzedniej wersji.
Wersje zmian powodujących niezgodność są ogłaszane za pośrednictwem artykułu z listą zmian powodujących niezgodność i opisu zmian w wersji GitHub. Publikacja wersji zapoznawczej/wersji kandydata na wydanie poprzedza niezgodność wersji, chyba że zmiany rozwiążą krytyczne problemy z zabezpieczeniami, prywatnością lub prawem. Chociaż poprzednie wersje konstruktora interfejsu API danych mogą pozostać dostępne na stronie wersji usługi GitHub, zalecamy uaktualnienie do najnowszej wersji, co może obejmować poprawki błędów.
Wersje zapoznawcza
Wersje zapoznawcza konstruktora interfejsu API danych są identyfikowane ze schematem X.Y.Z-rc przechowywania wersji. Sufiks wskazuje, że kompilacja -rc jest "kandydatem do wydania". Wersje zapoznawcza służą do zbierania opinii o nowych funkcjach i innych zmianach.
Jeśli nie planujemy celowo wprowadzać znaczących zmian z ostatniej stabilnej wersji, publikujemy następną wersję zapoznawcza ze wszystkimi elementami od najnowszej stabilnej wersji i nowych funkcji w wersji zapoznawczej. Następna aktualizacja konstruktora interfejsu API danych może spowodować przerwanie niektórych nowych funkcji w wersji zapoznawczej dodanych między wersjami wersji zapoznawczej. To zachowanie powodujące niezgodność oznacza, że może być konieczne zmianę kodu, aby wszystko działało ponownie.
Wersje w wersji zapoznawczej nie są przeznaczone do użytku długoterminowego ani produkcyjnego. Gdy nowa stabilna lub zapoznawcza wersja zapoznawcza stanie się dostępna, starsze wersje wersji zapoznawczej mogą być już niedostępne. Najlepiej używać wersji zapoznawczej tylko wtedy, gdy aktywnie pracujesz nad nowymi funkcjami i wszystko jest gotowe do przełączenia się do wersji innej niż wersja zapoznawcza wkrótce po wydaniu. Jeśli niektóre funkcje z wersji zapoznawczej są uwzględnione w nowej stabilnej wersji, pozostałe funkcje w wersji zapoznawczej zostaną dodane do nowej wersji zapoznawczej, aby wypróbować.
Tabela zmian wersji
Ważne
Możemy wprowadzić zmianę powodującą niezgodność w wersji pomocniczej lub poprawkowej, gdy zmiana dotyczy krytycznych usterek produktu, kwestii prawnych, bezpieczeństwa lub prywatności.
| Typ wydania | Poprzednia wersja | Nowa wersja | Uwagi |
|---|---|---|---|
| Zmiana kluczowa | 1.Y.Z |
2.Y.Z |
Nowe funkcje i poprawki błędów wraz z wszelkimi zmianami powodującymi niezgodność. |
| Stable | 1.1.Z |
1.2.Z |
Nowe funkcje i poprawki błędów bez zmian powodujących niezgodność, chyba że zmiany dotyczą krytycznych usterek produktu, kwestii prawnych, zabezpieczeń lub prywatności. |
| Stable | 1.1.1 |
1.1.2 |
Poprawki błędów bez nowych funkcji lub zmian powodujących niezgodność, chyba że zmiany dotyczą krytycznych usterek produktu, kwestii prawnych, zabezpieczeń lub prywatności. |
| Wersja zapoznawcza | X.Y.1-rc |
X.Y.2-rc |
Nowe funkcje w wersji zapoznawczej i poprawki błędów. (Zmiany powodujące niezgodność są uwzględniane, jeśli wersja główna zostanie wyboista). |
Zmiany powodujące niezgodność
Aby określić priorytety zabezpieczeń, ulepszyć funkcje i zachować jakość kodu, nowe wersje naszego oprogramowania mogą obejmować zmiany powodujące niezgodność. Chociaż dążymy do zminimalizowania tych zmian poprzez staranne wybory architektoniczne, mogą one nadal występować. W takich przypadkach priorytetem jest ogłoszenie ich i dostarczenie możliwych rozwiązań.
Ważne
Możemy wprowadzać zmiany bez wcześniejszego powiadomienia, jeśli zmiana jest uznawana za niezgodną lub czy jest to zmiana powodująca niezgodność w celu rozwiązania krytycznych usterek produktu lub kwestii prawnych, bezpieczeństwa lub prywatności.
Co to jest zmiana powodująca niezgodność?
Zmiana powodująca niezgodność to modyfikacja, która wymaga zaktualizowania aplikacji w celu uniknięcia zakłóceń. W konstruktorze interfejsu API danych zmiany powodujące niezgodność mogą obejmować zmiany kontraktów interfejsu API REST, generowanie schematu GraphQL i inne elementy wpływające na zgodność i funkcjonalność.
Przykłady zmian powodujących niezgodność
W poniższych przykładach przedstawiono niewyczerpaną listę zmian powodujących niezgodność w konstruktorze interfejsu API danych:
- Modyfikacje kontraktu interfejsu API REST
- Zmiany w generowaniu schematu GraphQL
- Zmiany wpływające na zgodność z poprzednimi wersjami
- Usuwanie lub zmienianie nazw interfejsów API lub parametrów
- Zmiany w kodach błędów
- Korekty funkcji definicji uprawnień
- Usuwanie dozwolonych parametrów, pól żądania lub pól odpowiedzi
- Dodawanie obowiązkowych parametrów lub pól żądania bez wartości domyślnych
- Modyfikacje zamierzonej funkcjonalności punktu końcowego interfejsu API
Definicja niełamającej się zmiany
Zmiana powodująca niezgodność odnosi się do zmiany, którą można zintegrować z aplikacją bez zakłóceń. Zmiany bez złamania są zwykle przekazywane po implementacji. Aplikacja powinna być zaprojektowana tak, aby obsługiwała te zmiany bez wcześniejszego powiadomienia.
Przykłady zmian powodujących niezgodność
Poniższe przykłady to niewyczerpana lista niezwiązanych zmian w konstruktorze interfejsu API danych:
- Wprowadzenie nowych punktów końcowych
- Dodawanie metod do istniejących punktów końcowych
- Włączenie nowych pól w odpowiedziach i żądaniach
- Korekty kolejności pól w odpowiedziach
- Wprowadzenie opcjonalnych nagłówków żądań
- Zmiany długości danych i rozmiaru odpowiedzi
- Zmiany w komunikatach o błędach i kodach
- Poprawki kodów odpowiedzi HTTP
- Dodatkowe metadane w wygenerowanych dokumentach OpenAPI
Jak komunikujemy zmiany powodujące niezgodność?
Priorytetem jest szybkie informowanie o zmianach powodujących niezgodność. Powiadomienia o zmianach powodujących niezgodność można znaleźć w informacjach o wersji wydań konstruktora interfejsu API danych w usłudze GitHub oraz w dedykowanym artykule dotyczącym zmian powodujących niezgodność.
Bieżąca lista zmian powodujących niezgodność
Zmiany powodujące niezgodność i wycofywanie funkcji są ogłaszane w tym artykule.
- Od tej pory nie ma żadnych zmian powodujących niezgodność