...

• Ett API skall versionshanteras i två nivåer (exempel: 1.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)

Hantera brytande versioner i applikationen

Den bakomliggande applikationen ska fortsätta ha stöd för både den nya och den gamla versionen av API’t även vid brytande förändringar så länge den gamla versionen används.

Ett exempel:
Fältet “facility” ska gå från att vara ett enda objekt till att bli en array (“facilities”). Det blir en brytande förändring eftersom fältet byter namn samt att det blir ett nytt format. Detta kan hanteras i applikationen genom att låta fältet “facility” ligga kvar parallellt med det nya fältet “facilities”. I applikationen krävs ibland en speciell validering under tiden dessa versioner ligger parallellt. Märk ut dessa temporära lösningar med TODO-kommentarer för att enkelt kunna hitta det som behöver uppdateras senare när den gamla versionen tas ur produktion.

Tips för att dölja det gamla fältet “facility” i den nya API-versionen i OpenAPI-specifikationen:

Lägg denna annotation på klassvariabeln:

@Schema(hidden = true)

Hur konfigurerar vi APIer i API Manager?

...