Versions Compared

Old Version 3

changes.mady.by.user Per Persson

Saved on

compared with

New Version Current

changes.mady.by.user Per Persson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Page Properties
label

Status

Status
colourYellowGreen
titleIn progressdecided

Impact

Status
colourGreen
titleLow

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

Alternativ 3

Bakgrund

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

...

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)

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

Beslut

...

Alternativ 3