Riktlinjer för versionshantering av APIer i API Manager

Status	decided
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	Mar 31, 2021
Outcome	Alternativ 3

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)

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

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

Spretigt för våra API-konsumenter

Enkel och rakt på

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

Tydligare livscykelhantering

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

Något mer administration än i alternativ 2

Klart tydligast livscykelhantering

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

Mer administration än i alternativ 3

Omröstning

@Jens Albonius (Unlicensed) - Jag ser hellre att det är resurserna som versionshanteras än det faktiska API:et

@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.

@Joel Lindberg (Unlicensed) Visar tydligt när en ändring skett men är inte så mycket jobb med själva versionshanteringen.

@Former user (Deleted) Tydlig nog

@Isak Styf (Unlicensed) Om vi nu skall ha versionsnummer i våra API:er så är detta den bästa kompromissen när det gäller antalet nivåer. Vi behöver dock diskutera ett antal frågor kring livscykelhanteringen så att det blir tydligt hur vi gör med gamla versioner och hur länge vi garanterar support på dessa.

Actions

@Isak Styf (Unlicensed)@Joel Lindberg (Unlicensed)@Dennis Nilsson (Unlicensed)@Lamin Saidy (Unlicensed)@Former user (Deleted)@Jens Albonius (Unlicensed) - vilket alternativ röstar ni på och varför - markera ovan (sen bestämmer jag vilket det blir ).

Beslut

Alternativ 3