Szabályzatok a Data API Builderhez
A szabályzatok egy halmaza szabályozza a Data API Buildert a kompatibilitástörő változásokhoz, értesítésekhez, kiadásokhoz és verziószámozáshoz kapcsolódóan.
Verziószámozás és kiadások
A Data API Builder környezetében megjelenő kiadás a szoftver minden közzétett verziójára vonatkozik, amelyet a Major.Minor.Patch formátum azonosít. Ezek a kiadások három kategóriába sorolhatók: stabil, kompatibilitástörő változás és előzetes verzió.
Stabil kiadások
A Data API Builder stabil verziója visszamenőlegesen kompatibilis. A visszamenőleges kompatibilitás azt jelenti, hogy a Data API Builder egy verziójára támaszkodó kód egy újabb stabil verziót alkalmazhat anélkül, hogy kódmódosításokat kellene végrehajtania a helyesség vagy a meglévő funkciók fenntartása érdekében.
Kompatibilitástörő változáskiadások
A Data API Builder kompatibilitástörő változásverziója nem kompatibilis visszamenőlegesen. A kompatibilitástörő változás verziójának meglévő ügyfélkódban való bevezetése kódmódosítást igényelhet, hogy az ügyfél pontosan ugyanúgy viselkedjen, mint az előző verzió megcélzásakor.
A kompatibilitástörő változásverziókat a kompatibilitástörő változáslistáról szóló cikk és a GitHub-kiadás változásleírása ismerteti. Az előzetes verzióra/kiadásra jelölt verzió közzététele megelőzi a kompatibilitástörő változásverziókat, hacsak a módosítások nem oldják meg a kritikus biztonsági, adatvédelmi vagy jogi problémákat. Bár a Data API Builder korábbi verziói továbbra is elérhetők maradhatnak a GitHub-kiadások oldalán, javasoljuk, hogy frissítsen a legújabb kiadásra, amely hibajavításokat is tartalmazhat.
Előzetes kiadások
A Data API Builder előzetes kiadásait a verziószámozási X.Y.Z-rc séma azonosítja. Az -rc utótag azt jelzi, hogy a build egy "kiadási jelölt". Az előzetes kiadások az új funkciókkal és egyéb módosításokkal kapcsolatos visszajelzések gyűjtésére szolgálnak.
Hacsak nem tervezzük, hogy szándékosan jelentős módosításokat hajtunk végre az utolsó stabil verziónál, közzétesszük a következő előzetes verziót a legújabb stabil kiadás és az új előzetes verzió funkcióival. A Data API Builder következő frissítése megszakíthat néhány új előzetes verziójú funkciót, amelyeket az előzetes verziók között adtunk hozzá. Ez a kompatibilitástörő viselkedés azt jelenti, hogy módosítania kell a kódot, hogy a dolgok újra működjenek.
Az előzetes verziók nem hosszú távú vagy éles használatra szolgálnak. Ha egy új stabil vagy előzetes verzió elérhetővé válik, előfordulhat, hogy a régebbi előzetes verziók már nem lesznek elérhetők. Az előzetes verziókat csak akkor érdemes használni, ha aktívan dolgozik az új funkciókon, és készen áll arra, hogy nem előzetes verzióra váltson a megjelenés után. Ha az előzetes verzió egyes funkcióit egy új stabil verzió tartalmazza, a többi előzetes verziót hozzáadjuk egy új előzetes verzióhoz, hogy kipróbálhassa.
Verziómódosítási táblázat
Fontos
Előfordulhat, hogy kompatibilitástörő változást vezetünk be egy kisebb vagy javításos kiadásban, ha a módosítás kritikus termékhibákat, jogi, biztonsági vagy adatvédelmi problémákat old meg.
| Kiadás típusa | Előző verzió | Új verzió | Jegyzetek |
|---|---|---|---|
| Kompatibilitástörő változás | 1.Y.Z |
2.Y.Z |
Új funkciók és hibajavítások, valamint az esetleges kompatibilitástörő változások. |
| Stable | 1.1.Z |
1.2.Z |
Új funkciók és hibajavítások kompatibilitástörő változások nélkül, kivéve, ha a módosítások nem érintik a termék kritikus hibáit, jogi, biztonsági vagy adatvédelmi aggályait. |
| Stable | 1.1.1 |
1.1.2 |
Új funkciók és kompatibilitástörő változások nélküli hibajavítások, kivéve, ha a módosítások nem érintik a termék kritikus hibáit, jogi, biztonsági vagy adatvédelmi aggályait. |
| Előnézet | X.Y.1-rc |
X.Y.2-rc |
Új előzetes verziójú funkciók és hibajavítások. (A kompatibilitástörő változások akkor jelennek meg, ha a főverzió ütközik.) |
Kompatibilitástörő változások
A biztonság rangsorolása, a funkciók javítása és a kódminőség fenntartása érdekében szoftverünk új verziói kompatibilitástörő változásokat is tartalmazhatnak. Bár körültekintő architektúraválasztással igyekszünk minimalizálni ezeket a változásokat, továbbra is előfordulhatnak. Ilyen esetekben prioritást élveznek azok bejelentése és a lehetséges megoldások biztosítása.
Fontos
Előzetes értesítés nélkül végezhetünk módosításokat, ha a módosítást nem kompatibilitástörőnek tekintik, vagy ha a kritikus termékhibák, illetve jogi, biztonsági vagy adatvédelmi problémák kezelése érdekében kompatibilitástörő változásról van szó.
Mi az a kompatibilitástörő változás?
A kompatibilitástörő változás olyan módosítás, amely megköveteli az alkalmazás frissítését a fennakadások elkerülése érdekében. A Data API Builderben a kompatibilitástörő változások közé tartozhatnak a REST API-szerződések módosítása, a GraphQL-séma létrehozása és a kompatibilitást és a funkcionalitást befolyásoló egyéb elemek.
Kompatibilitástörő változási példák
Az alábbi példák a Data API Builder kompatibilitástörő változásainak nem kimerítő listája:
- REST API-szerződésmódosítások
- Változások a GraphQL-sémalétrehozásban
- A visszamenőleges kompatibilitást befolyásoló módosítások
- API-k vagy paraméterek eltávolítása vagy átnevezése
- Hibakódok változásai
- Az engedélydefiníció funkcióinak módosítása
- Az engedélyezett paraméterek, kérelemmezők vagy válaszmezők eltávolítása
- Kötelező paraméterek vagy kérésmezők hozzáadása alapértelmezett értékek nélkül
- A kívánt API-végpont funkcióinak módosítása
Nem törhető változás definíciója
A nem kompatibilitástörő változások olyan változásokra utalnak, amelyek megszakítás nélkül integrálhatók az alkalmazásba. A nem törhető módosításokat általában az implementáció után közlik. Az alkalmazást úgy kell megtervezni, hogy előzetes értesítés nélkül kezelje ezeket a módosításokat.
Nem kompatibilitástörő változási példák
Az alábbi példák a Data API Builder nem törhető módosításainak nem kimerítő listája:
- Új végpontok bemutatása
- Metódusok hozzáadása meglévő végpontokhoz
- Új mezők beépítése a válaszokba és a kérelmekbe
- A mezősorrend módosítása a válaszokon belül
- A választható kérésfejlécek bemutatása
- Az adathossz és a válasz méretének módosítása
- A hibaüzenetek és a kódok módosítása
- A HTTP-válaszkódok javításai
- További metaadatok a létrehozott OpenAPI-dokumentumokban
Hogyan kommunikáljunk a kompatibilitástörő változásokról?
Prioritásként kezeljük, hogy azonnal tájékoztassa Önt a kompatibilitástörő változásokról. A kompatibilitástörő változásértesítéseket a Data API Builder GitHubon elérhető kiadásainak kibocsátási megjegyzéseiben és a dedikált kompatibilitástörő változások listájában találja.
Aktuális kompatibilitástörő változások listája
A kompatibilitástörő változásokat és a funkció kivonását ebben a cikkben ismertetjük.
- Jelenleg nincsenek kompatibilitástörő változások