Principer för data-API-byggare
En uppsättning principer styr Data API Builder som rör icke-bakåtkompatibla ändringar, meddelanden, versioner och versionshantering.
Versionshantering och versioner
En version i kontexten för Data API Builder refererar till varje publicerad version av programvaran, som identifieras av Major.Minor.Patch formatet. Dessa versioner delas in i tre kategorier: stabil, icke-bakåtkompatibel ändring och förhandsversion.
Stabila versioner
En stabil version av Data API Builder är bakåtkompatibel. Bakåtkompatibel innebär att all kod du skriver som förlitar sig på en version av en Data API-byggare kan anta en nyare stabil version utan att kräva några kodändringar för att upprätthålla korrekthet eller befintliga funktioner.
Icke-bakåtkompatibla ändringsversioner
En icke-bakåtkompatibel ändringsversion av Data API Builder är inte bakåtkompatibel. En icke-bakåtkompatibel ändringsversion i befintlig klientkod kan kräva kodändringar för att säkerställa att klienten beter sig exakt som den gjorde när den tidigare versionen riktades.
Icke-bakåtkompatibla ändringsversioner tillkännages via artikeln om icke-bakåtkompatibla ändringar och i en GitHub-versions ändringsbeskrivning. Publicering av en förhandsversion/versionsversion föregår icke-bakåtkompatibla ändringsversioner om inte ändringarna åtgärdar kritiska säkerhets-, sekretess- eller juridiska problem. Även om tidigare versioner av Data API Builder kan vara tillgängliga på GitHub-versionssidan rekommenderar vi att du uppgraderar till den senaste versionen, vilket kan innehålla felkorrigeringar.
Förhandsversioner
Förhandsversioner av Data API Builder identifieras med X.Y.Z-rc versionsschemat. Suffixet -rc anger att versionen är en "versionskandidat". Förhandsversioner används för att samla in feedback om nya funktioner och andra ändringar.
Såvida vi inte planerar att göra betydande ändringar från den senaste stabila versionen publicerar vi nästa förhandsversion med allt från den senaste stabila versionen och nya förhandsversionsfunktioner. Nästa uppdatering av Data API Builder kan bryta några av de nya förhandsversionsfunktionerna som vi har lagt till mellan förhandsversionerna. Det här icke-bakåtkompatibla beteendet innebär att du kan behöva ändra koden för att få saker att fungera igen.
Förhandsversioner är inte avsedda för långsiktig användning eller produktionsanvändning. När en ny stabil version eller förhandsversion blir tillgänglig kanske äldre förhandsversioner inte längre är tillgängliga. Det är bäst att bara använda förhandsversioner när du aktivt arbetar med nya funktioner och är redo att byta till en icke-förhandsversion strax efter lanseringen. Om vissa funktioner från en förhandsversion ingår i en ny stabil version läggs de återstående förhandsversionsfunktionerna till i en ny förhandsversion som du kan prova.
Versionsändringstabell
Viktigt
Vi kan införa en icke-bakåtkompatibel ändring av en mindre version eller korrigeringsversion när ändringen åtgärdar kritiska produktbuggar, juridiska problem, säkerhet eller sekretessproblem.
| Versionstyp | Tidigare version | Ny version | Kommentarer |
|---|---|---|---|
| Icke-bakåtkompatibel ändring | 1.Y.Z |
2.Y.Z |
Nya funktioner och felkorrigeringar samt eventuella icke-bakåtkompatibla ändringar. |
| Stable | 1.1.Z |
1.2.Z |
Nya funktioner och buggkorrigeringar utan icke-bakåtkompatibla ändringar såvida inte ändringarna åtgärdar viktiga produktbuggar, juridiska problem, säkerhet eller sekretessproblem. |
| Stable | 1.1.1 |
1.1.2 |
Buggkorrigeringar utan nya funktioner eller icke-bakåtkompatibla ändringar, såvida inte ändringarna åtgärdar viktiga produktbuggar, juridiska problem, säkerhet eller sekretessproblem. |
| Förhandsgranskning | X.Y.1-rc |
X.Y.2-rc |
Nya förhandsversionsfunktioner och felkorrigeringar. (Icke-bakåtkompatibla ändringar inkluderas om huvudversionen stöts.) |
Icke-bakåtkompatibla ändringar
För att prioritera säkerhet, förbättra funktioner och upprätthålla kodkvaliteten kan nya versioner av vår programvara omfatta icke-bakåtkompatibla ändringar. Vi strävar efter att minimera dessa ändringar genom noggranna arkitektoniska val, men de kan fortfarande inträffa. I sådana fall prioriterar vi att tillkännage dem och tillhandahålla möjliga lösningar.
Viktigt
Vi kan göra ändringar utan föregående meddelande om ändringen anses vara icke-bakåtkompatibel, eller om det är en icke-bakåtkompatibel ändring som görs för att åtgärda kritiska produktbuggar eller juridiska, säkerhetsrelaterade eller sekretessrelaterade problem.
Vad är en icke-bakåtkompatibel ändring?
En icke-bakåtkompatibel ändring är en ändring som kräver att du uppdaterar programmet för att förhindra avbrott. I Data API Builder kan icke-bakåtkompatibla ändringar inkludera ändringar i REST API-kontrakt, GraphQL-schemagenerering och andra element som påverkar kompatibilitet och funktionalitet.
Exempel på icke-bakåtkompatibla ändringar
Följande exempel är en outtömmande lista över icke-bakåtkompatibla ändringar i Data API Builder:
- Ändringar av REST API-kontrakt
- Ändringar i GraphQL-schemagenerering
- Ändringar som påverkar bakåtkompatibilitet
- Borttagning eller namnbyte av API:er eller parametrar
- Ändringar i felkoder
- Justeringar av behörighetsdefinitionsfunktioner
- Borttagning av tillåtna parametrar, begärandefält eller svarsfält
- Tillägg av obligatoriska parametrar eller begärandefält utan standardvärden
- Ändringar av avsedda API-slutpunktsfunktioner
Definition av en icke-indelningsändring
En icke-icke-bakåtkompatibel ändring refererar till en ändring som kan integreras i ditt program utan att orsaka avbrott. Icke-bakåtkompatibla ändringar kommuniceras vanligtvis efter implementeringen. Ditt program bör utformas för att hantera dessa ändringar utan föregående meddelande.
Icke-icke-icke-bakåtkompatibla ändringsexempel
Följande exempel är en obefintlig lista över icke-banbrytande ändringar i Data API Builder:
- Introduktion av nya slutpunkter
- Tillägg av metoder till befintliga slutpunkter
- Införlivande av nya fält i svar och begäranden
- Justeringar av fältordning inom svar
- Introduktion av valfria begärandehuvuden
- Ändringar av datalängd och svarsstorlek
- Ändringar av felmeddelanden och koder
- Korrigeringar av HTTP-svarskoder
- Extra metadata i genererade OpenAPI-dokument
Hur kommunicerar vi icke-bakåtkompatibla ändringar?
Vi prioriterar att informera dig snabbt om icke-bakåtkompatibla ändringar. Du hittar meddelanden om icke-bakåtkompatibla ändringar i viktig information om versioner av Data API Builder på GitHub och i den dedikerade listartikeln för icke-bakåtkompatibla ändringar.
Aktuell icke-bakåtkompatibel ändringslista
Icke-bakåtkompatibla ändringar och tillbakadragningar av funktioner tillkännages i den här artikeln.
- Från och med nu finns det inga icke-bakåtkompatibla ändringar