Zásady pro Tvůrce rozhraní API pro data
Tvůrce datového rozhraní API souvisejícího s zásadními změnami, oznámeními, verzemi a správou verzí se řídí sadou zásad.
Správa verzí a vydané verze
Vydání v kontextu Tvůrce rozhraní Data API odkazuje na každou publikovanou verzi softwaru, kterou identifikuje Major.Minor.Patch formát. Tyto verze spadají do tří kategorií: stabilní, zásadní změna a Preview.
Stabilní verze
Stabilní verze Tvůrce rozhraní Data API je zpětně kompatibilní. Zpětná kompatibilita znamená, že jakýkoli kód, který napíšete a spoléhá na jednu verzi Tvůrce rozhraní API pro data, může přijmout novější stabilní verzi bez nutnosti jakýchkoli změn kódu pro zachování správnosti nebo stávajících funkcí.
Zásadní změny vydané verze
Zásadní změna verze Tvůrce rozhraní Data API není zpětně kompatibilní. Přijetí verze zásadní změny v existujícím klientském kódu může vyžadovat změny kódu, aby se zajistilo, že se klient chová přesně tak, jak se choval při cílení na předchozí verzi.
Verze zásadních změn se oznamují prostřednictvím článku o seznamu zásadních změn a v popisu změn vydané verze GitHubu. Publikování verze Preview/release candidate předchází verzím zásadních změn, pokud změny neopraví kritické problémy se zabezpečením, ochranou osobních údajů nebo právními problémy. I když předchozí verze Tvůrce rozhraní Data API můžou zůstat dostupné na stránce vydání GitHubu, doporučujeme upgradovat na nejnovější verzi, která může zahrnovat opravy chyb.
Verze Preview
Verze Preview Tvůrce dat jsou identifikovány pomocí schématu X.Y.Z-rc správy verzí. Přípona -rc označuje, že sestavení je "kandidát verze". Verze Preview slouží ke shromažďování zpětné vazby k novým funkcím a dalším změnám.
Pokud neplánujeme záměrně provádět významné změny od poslední stabilní verze, publikujeme další verzi Preview se vším, co je součástí nejnovější stabilní verze a nových funkcí Preview. Další aktualizace Tvůrce rozhraní API pro data může narušit některé nové funkce preview, které jsme přidali mezi verzemi Preview. Toto chování způsobující chybu znamená, že možná budete muset změnit kód, aby vše znovu fungovalo.
Verze Preview nejsou určené pro dlouhodobé nebo produkční použití. Když bude k dispozici nová stabilní verze nebo verze Preview, starší verze Preview už nemusí být dostupné. Nejlepší je používat verze Preview jenom v případech, kdy aktivně pracujete na nových funkcích a jste připraveni brzy po vydání přejít na verzi bez verze Preview. Pokud jsou některé funkce z verze Preview součástí nové stabilní verze, zbývající funkce preview se přidají do nové verze Preview, kterou si můžete vyzkoušet.
Tabulka změn verzí
Důležité
V případě, že se tato změna týká kritických chyb produktu, právních problémů, zabezpečení nebo ochrany osobních údajů, můžeme zavést zásadní změnu menší verze nebo opravy.
| Typ verze | Předchozí verze | Nová verze | Poznámky |
|---|---|---|---|
| Narušující změna | 1.Y.Z |
2.Y.Z |
Nové funkce a opravy chyb spolu se všemi zásadními změnami |
| Stable | 1.1.Z |
1.2.Z |
Nové funkce a opravy chyb bez zásadních změn, pokud tyto změny neřeší kritické chyby produktů, právní problémy, zabezpečení nebo ochranu osobních údajů. |
| Stable | 1.1.1 |
1.1.2 |
Opravy chyb bez nových funkcí nebo zásadních změn, pokud tyto změny neřeší kritické chyby produktů, právní záležitosti, zabezpečení nebo ochranu osobních údajů. |
| Preview | X.Y.1-rc |
X.Y.2-rc |
Nové funkce ve verzi Preview a opravy chyb (Změny způsobující chybu se zahrnou, pokud dojde k narušení hlavní verze.) |
Zásadní změny
Nové verze našeho softwaru můžou obsahovat zásadní změny, aby bylo možné stanovit prioritu zabezpečení, vylepšovat funkce a udržovat kvalitu kódu. I když se snažíme tyto změny minimalizovat pečlivým výběrem architektury, stále k nim může dojít. V takových případech upřednostňujeme jejich oznámení a poskytnutí možných řešení.
Důležité
Změny můžeme provádět bez předchozího upozornění, pokud je tato změna považována za neporušnou nebo pokud se jedná o zásadní změnu, která řeší kritické chyby produktu nebo právní, bezpečnostní nebo soukromé záležitosti.
Co je zásadní změna?
Změna způsobující chybu je úprava, která vyžaduje aktualizaci aplikace, abyste zabránili přerušení. V Tvůrci rozhraní API pro data můžou zásadní změny zahrnovat změny kontraktů rozhraní REST API, generování schématu GraphQL a další prvky, které ovlivňují kompatibilitu a funkčnost.
Příklady zásadních změn
Následující příklady jsou nevyčerpatelný seznam zásadních změn v Tvůrci rozhraní Data API:
- Úpravy kontraktů rozhraní REST API
- Změny generování schématu GraphQL
- Změny ovlivňující zpětnou kompatibilitu
- Odebrání nebo přejmenování rozhraní API nebo parametrů
- Změny v kódech chyb
- Úpravy funkcí definice oprávnění
- Odebrání povolených parametrů, polí požadavků nebo polí odpovědi
- Přidání povinných parametrů nebo polí požadavků bez výchozích hodnot
- Úpravy zamýšlených funkcí koncového bodu rozhraní API
Definice nezlomné změny
Zásadní změna označuje změnu, která se dá integrovat do aplikace, aniž by způsobila přerušení. Nezlomné změny se obvykle sdělují po implementaci. Aplikace by měla být navržená tak, aby tyto změny zvládla bez předchozího upozornění.
Příklady nezlomných změn
Následující příklady jsou nevyčerpatelný seznam nepřerušovaných změn v Tvůrci rozhraní Data API:
- Zavedení nových koncových bodů
- Přidání metod do existujících koncových bodů
- Začlenění nových polí do odpovědí a požadavků
- Úpravy pořadí polí v odpovědích
- Zavedení volitelných hlaviček požadavků
- Změny délky dat a velikosti odpovědi
- Změny chybových zpráv a kódů
- Opravy kódů odpovědí HTTP
- Další metadata ve vygenerovaných dokumentech OpenAPI
Jak komunikujeme změny způsobující chybu?
Prioritně vás musíme informovat o zásadních změnách. Oznámení o zásadních změnách najdete v poznámkách k verzím nástroje Data API Builder na GitHubu a ve vyhrazeném článku se seznamem zásadních změn.
Aktuální seznam zásadních změn
V tomto článku jsou oznámeny zásadní změny a vyřazení funkcí.
- V současné chvíli nedošlo k žádným zásadním změnám.