Översikt

Publicering på plattformen sker i fyra faser:

1. Förberedelse — du har en bakomliggande tjänst och en OpenAPI-spec.
2. Onboarding — integrationsplattformen kopplar in tjänsten bakom Gateway:n.
3. Test — API:et publiceras i test-miljön och du verifierar flödena.
4. Produktion — API:et släpps till prod och listas i katalogen.

Hela processen styrs av Terraform — alla API:er, versioner och spec-filer versionshanteras i kong-konnect-terraform.

1. Innan du tar kontakt

Innan du hör av dig — säkerställ följande:

• Tjänsten är driftsatt i en miljö som är nåbar från Gateway:n (typiskt internt nätverk eller Azure VNet med peering).
• OpenAPI-specen är giltig och följer riktlinjerna i Dokumentera API:er.
• Du vet vilka scopes API:et behöver — finkornighet på operationsnivå om möjligt (t.ex. foreningar.read, foreningar.write).
• Du har en kontaktperson som äger API:et över tid (förvaltning, team eller person).

2. Begär onboarding

Mejla it-integrationer@uppsala.se med:

• API-namnets föreslagna URL-prefix (/foreningar, /medborgare, etc.).
• Länk till OpenAPI-specen (eller bifoga filen).
• Bakomliggande tjänstens host och port.
• Lista över scopes och kort motivering.
• Kontaktperson + förvaltning.

Plattformen återkopplar med en plan, ett API-ID och en branch i Terraform- repot där publiceringen kommer att ske.

3. Publicering i test

Plattformen lägger till ditt API i infra/test/catalog/:

resource "konnect_api" "foreningar" {
  name        = "Föreningsregister"
  description = "API för Uppsala kommuns föreningsregister"
  labels = {
    environment = "test"
    managed-by  = "terraform"
    owner       = "kulturforvaltningen"
  }
}

resource "konnect_api_version" "foreningar_v1" {
  api_id  = konnect_api.foreningar.id
  version = "1.0.0"
  spec = {
    content = file("${path.module}/specs/foreningar.yaml")
  }
}

Efter terraform apply syns ditt API i katalogen i test-miljön. Nu är det din tur att verifiera:

• Endpoints svarar med rätt statuskoder.
• Autentisering fungerar — testa både med och utan giltig token.
• Scopes håller — en token utan scope ska få 403, inte 401 eller 200.
• Felhantering — testa medvetet felaktiga anrop och kontrollera svaren.

Hittar du problem — uppdatera specen eller tjänsten och be plattformen köra en ny terraform apply.

4. Release till produktion

När test-miljön ser bra ut publicerar plattformen samma resurs i infra/prod/catalog/. Innan släpp:

• En kort release-not läggs till i konnect_api_document så konsumenter ser vad som ändras.
• Kontaktpersonen får en godkännandekoll via mejl.
• Plattformen kör terraform apply mot prod under planerad deploy-tid.

Efter release är ditt API publikt synligt i katalogen och kan konsumeras enligt Kom igång.

Versionering och ändringar

• Bakåtkompatibla ändringar (nya valfria fält, nya endpoints) — bumpa patch-version (1.0.0 → 1.0.1) och uppdatera specen.
• Bakåtinkompatibla ändringar — skapa en ny konnect_api_version- resurs (2.0.0) parallellt med den gamla. Markera den gamla som deprecated och ge konsumenter minst 3 månader att migrera innan den tas bort.
• Akuta säkerhetsfixar kan ske utanför normal release-cykel — kontakta plattformen direkt.

Mer om det praktiska — se Terraform-repots README.