Instansstrategi

APIer skall finnas i tre instanser:

• Sandbox - en mockad testversion som returnerar statiska svar (inga integrationer mot andra applikationer eller system)

• Test - en testversion som integrerar mot andra applikationers eller systems testmiljöer

• Produktion - produktionsversion som integrerar mot andra applikationers eller systems produktionsmiljöer

Versionshantering

Observera 1: detta gäller produktionsmiljön!

Observera 2: om ett API säkras med API Key så måste respektive klient få en ny nyckel skapad för den nya versionen av APIet!

• 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?

Test

Konfigureras i API Publisher Test (https://api-im-test.sundsvall.se/publisher/apis).

• Sandbox Endpoint skall peka på Sandbox-versionen av mikrotjänsten/applikationen

• Production Endpoint skall peka på testversionen av mikrotjänsten/applikationen

Produktion

Konfigureras i API Publisher produktion (https://api-im.sundsvall.se/publisher/apis).

• Production Endpoint skall peka på produktionsversionen av mikrotjänsten/applikationen