Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

Status

IN PROGRESS

Impact

LOW

Driver

Per Persson 

Approver

Per Persson

Contributors

Per Persson Isak Styf (Unlicensed) Joel Lindberg (Unlicensed) Dennis Nilsson (Unlicensed) Lamin Saidy (Unlicensed) Former user (Deleted) Jens Albonius (Unlicensed)

Informed

Due date

Outcome

Bakgrund

På API-design säger vi “APIer skall versionshanteras“.

På https://utveckling.sundsvall.se/riktlinjer-for-utveckling/api-utveckling-forvaltning-regler-och-riktlinjer/ säger vi “Ett API skall versionshanteras i (minst) två nivåer (exempel: version 1.0)”.

Kanske behöver vi en mer detaljerad och tydlig riktlinje över hur vi vill versionshantera APIer i API Gateway (oavsett hur versionshantering av de applikationer som producerar APIer ser ut).

Alternativ

Riktlinjer för API-versionering i API Manager

Alternativ 1:
Vi lämnar det fritt för API-producenten

Alternativ 2:

En nivå, v1, v2, v3, …

Alternativ 3:

Två nivåer, 1.0, 1.1, 2.0, …

  • En API-förändring som bryter kontraktet (som gör att APIet inte är bakåtkompatibelt) skall resultera i att man stegar upp huvudversionen (från till exempel 1.0 till 2.0)

  • En API-förändring som endast lägger till nya resurser eller parametrar till ett API (som gör att APIet är bakåtkompatibelt) skall resultera i att man stegar upp inom huvudversionen (från till exempel 1.0 till 1.1)

Alternativ 4:

Tre nivåer, 1.0.0, 1.0.1, 1.1.0, 2.0.0 …

  • En API-förändring som bryter kontraktet (som gör att APIet inte är bakåtkompatibelt) skall resultera i att man stegar upp huvudversionen (från till exempel 1.0.0 till 2.0.0)

  • En API-förändring som endast lägger till nya resurser eller parametrar till ett API (som gör att APIet är bakåtkompatibelt) skall resultera i att man stegar upp inom huvudversionen på nivå två (från till exempel 1.0.0 till 1.1.0)

  • En API-förändring som ändrar datamängder i ett API (t ex utökar antal val i en ENUM) skall resultera i att man stegar upp inom huvudversionen på nivå tre (från till exempel 1.0.0 till 1.0.1)

Pros and cons

(plus) Enklast möjliga för våra API-producenter

(minus) Spretigt för våra API-konsumenter

(plus) Enkel och rakt på

(minus) Ingen indikation på om en versionsuppdatering är bakåtkompatibel eller ej

(plus) Tydligare livscykelhantering

(plus) Indikation om en versionsuppdatering är bakåtkompatibel eller ej tillgänglig

(minus) Något mer administration än i alternativ 2

(plus) Klart tydligast livscykelhantering

(plus) Indikation om en versionsuppdatering är bakåtkompatibel eller ej tillgänglig

(minus) Mer administration än i alternativ 3

Omröstning (smile)

Per Persson - inte särskilt betungande, men ger ändå bra koll på livscykeln.

Dennis Nilsson (Unlicensed) - Tillräckligt för att ha en tydlig versionshantering.

Action items

Outcome

  • No labels