Zum Hauptinhalt springen

ADR: Routen-Format des API-Gateways (api.togethercca.com)

🤖 Generated with Claude Code

⚠️ Not yet reviewed – KI-Vorschlag als Diskussionsgrundlage, keine Entscheidung

Co-Authored-By: Claude (noreply@anthropic.com)

Status: Draft – unreviewter KI-Vorschlag Date: 2026-11 Scope: api.togethercca.com (TOGETHER API-Gateway), tis.identity (Tenant-Claims), alle tis.partner.*Integration, CCA

StatusVorgeschlagen (Draft)
DokumenteRegistry · Cheat Sheet (HTML) · Gateway-Repo api.togethercca.com
Gilt fĂĽralle Maschinen-Schnittstellen, die wir oder unsere Partner ĂĽber die TOGETHER-Plattform anbieten
Gilt nicht fĂĽrRouten der TOGETHER-WebApp (Browser-Traffic auf www.servicebytogether.at)

1. Kontext​

  • Clients brauchen stabile URLs, auch wenn sich bei einer VU Umgebung, Host oder Version ändert.
  • CCA kann nicht on-demand ausgerollt werden. Installationen im Feld hängen teilweise mehrere Releases zurĂĽck (8 Releases/Jahr, Schema YYYY-ReleaseNr). Eine URL- oder Contract-Ă„nderung muss daher auch fĂĽr alte Installationen weiter bedient werden.
  • VUs, Vendoren und Partner können an ihrem Endpunkt jederzeit einen Breaking Change einbauen. Wir erfahren davon häufig erst im Nachhinein und mĂĽssen dann fĂĽr bestimmte CCA-Releases reagieren können, ohne diese Releases anfassen zu können.
  • Routing-Entscheidungen nach Sparte oder VU-Version am Gateway haben sich als wenig hilfreich erwiesen: bei jeder Vereinbarung zwischen Riskine und einer VU mussten beide Seiten ändern. Diese Entscheidungen gehören in die Integration-Services (BoaApi, tis.partner.*Integration), nicht ins Routing. BoaBot wird kĂĽnftig ĂĽber die BoaApi zugreifen; Riskine macht die VU-Anbindungen damit nicht mehr direkt.
  • Es bleiben als Caller: interne Produkte (BoA*, CCA9), GroĂźkunden mit unserem Usermanagement (Ă–AMTC, Greco), die VIG-Anbindungen (ca. 15 externe OMDS3-Partner, On-Boarding durch Christian Swoboda). Eine allgemeine OMDS3-Drehscheibe ist nicht Realität geworden.
  • Die alten Reverse-Proxies (www.servicebytogether.at, b2b.servicebytogether.at, Helicon Ape/ISAPI) exponieren interne Deploy-Namen als öffentliche URL (/tis.gf.boaapi/, /tis.partner.uniqaIntegration/, /axis2/services/SOAGFX_2_0) und reichen die meisten API-Pfade am Edge anonym durch. Jeder Umzug einer Anwendung ist dort ein Breaking Change fĂĽr Clients.
  • Am Gateway existieren bereits Routen unter /partner/..., /customers/... sowie Legacy-Routen /services/... und /omds3services/....

2. Entscheidung​

2.1 Vier Namensräume – die erste Entscheidung​

Jede Route liegt in genau einem von vier Namensräumen. Welcher, ist die erste Frage bei jeder neuen Route und wird vor allem anderen beantwortet. In dieser Reihenfolge prüfen, der erste Treffer gilt:

#NamensraumDer Caller ist …BeispieleGehört nicht hierher
1/products/unser Produkt – unabhängig davon, wer es entwickelt. Produkt schlägt Partner.cca, boa-api, boabot (Entwicklung: Riskine, Produkt: unseres)Riskine mit eigenen Produkten → /partners/
2/partners/eine VU oder ein Integrations-Partner mit eigener Plattform-Anbindung – System-Kontext, das fremde System ist der Akteur, kein Makler-Principalvig, generali, uniqa, ergo, riskineSoftware und Portale, die unsere Kunden verwenden → /3rd-party/
3/customers/eine Kundenorganisation, die für sich selbst ruft – Makler-Büro-Kontext, der Client ist an eine Organisation bzw. feste MaklerIds gebundenoeamtc, greco, ovb, efs, versfinanz, oebvSoftware, die von vielen Büros genutzt wird → /3rd-party/
4/3rd-party/Fremdsoftware oder Portal, das unsere Kunden einsetzen – User-Kontext, die Organisation kommt erst aus dem User-Token; hinter einem Client stehen viele Makler-Bürosvers-admin-m, onlineordner, basic-systems, cheggnet, durchblickerunsere eigenen Produkte, auch wenn fremdentwickelt → /products/

Abgrenzungskriterium (Vorschlag, zu prüfen): der Kontext des Tokens, nicht die Geschäftsbeziehung oder der Name.

KontextTokenBeispiel
/partners/System-Kontext – das fremde System selbst ist der Akteur, kein Makler-Principalclient_credentials / IP-Filter, oder Token-Exchange mit delegation_scope: together:all-usersGenerali ändert einen Geschäftsfall; VIG holt CADS-Daten ab
/customers/Makler-Büro-Kontext, eine Organisation – der Client selbst ist an die Organisation gebundenClient-Token mit Berechtigung auf bestimmte MaklerIds (delegation_scope: maklerid:…, Scope auf eigene Vermittler) oder User-Token aus eigener Software der OrganisationÖBV-Client handelt für Makler 101745; OVB verwaltet eigene Accounts
/3rd-party/User-Kontext, viele Organisationen – die Organisation ergibt sich erst aus dem eingeloggten MaklerUser-Token (authorization_code) aus einer Software, die n Büros nutzenOnlineOrdner lädt Bestand für einen Makler; cheggnet tarifiert für 609 Makler-Konten

Das Kriterium ist am Token prüfbar und deckt sich mit den heutigen Identity-Clients (alle VU-Clients client_credentials; alle Organisations- und App-Clients authorization_code; riskine.omds3.client trägt together:all-users, oebv.omds3.client trägt maklerid:101745). Mit /3rd-party/ als eigenem Namensraum ist die Frage „Organisation oder App auf {caller}-Ebene“ beantwortet: unter /3rd-party/ ist der Caller die App, die Organisation des Maklers ist eine zweite Dimension aus dem User-Token (Telemetrie, Rate-Limit pro App und pro Büro). Unter /customers/ ist der Caller die Organisation. Grenzfälle werden nach dem Token-Kriterium entschieden: Client an feste MaklerIds gebunden → /customers/, Organisation erst aus dem User → /3rd-party/.

Autorenschaft ist irrelevant – entscheidend ist, an wen der Zugang gebunden ist. Das ist dieselbe Regel wie Produkt schlägt Partner (BoaBot: entwickelt von Riskine, Produkt von uns → /products/), gespiegelt: Baut ein Softwarehaus die Anbindung für eine Kundenorganisation (FB-Research für Swiss Life Select), ist das der Zugang dieser Organisation → /customers/sls, Client mit tis_tenant: sls. Der Vorteil ist das Binding: ein /customers/-Client kann nicht unbemerkt zum Multi-Tenant-Client werden. Erst wenn das Softwarehaus mit eigenem Client mehrere Kunden anbindet, entsteht /3rd-party/{software} – die URL des ersten Kunden bleibt davon unberührt.

Ausnahme: Riskine ruft SOAGFX sowohl fĂĽr eigene Produkte als auch fĂĽr BoaBot ĂĽber /partners/riskine/soagfx; eine getrennte Route /products/boabot/soagfx ist nicht erforderlich.

2.2 Grammatik je Namensraum​

/partners/{caller}[/{target}[-{targetEnv}]]/{service}/{**path}
/customers/{caller}[/{target}[-{targetEnv}]]/{service}/{**path}
/3rd-party/{caller}[/{target}[-{targetEnv}]]/{service}/{**path}
/products/{caller}[/{target}[-{targetEnv}]]/{service}/{**path} caller ≠ cca
/products/cca/{release}[/{target}[-{targetEnv}]]/{service}/{**path} Release-Key, siehe 2.3

Die vier Namensräume sind Literale, kein variables Segment. Die restlichen Segmente sind in allen Formen gleich. Das Gateway schreibt kein Versions-Segment vor – ob und wie ein Service seinen Contract versioniert, entscheidet der Service (siehe 2.3).

SegmentBedeutungRegeln
callerwer ruftSlug aus der Registry (Abschnitt 2.6). Muss zur Identität des Tokens passen (Abschnitt 2.4).
targetVU, deren Service über unseren Integration-Service erreicht wirdoptional. Vorhanden ⇔ der Service gehört einer VU (Pass-Through). Fehlt ⇔ der Service ist unser eigener.
targetEnvAbweichung von der Default-Umgebung der VUoptional, geschlossen: maint, test. Ohne Suffix ist die Default-Umgebung der VU gemeint. Welche das ist, hängt von unserer Umgebung ab: api und api-pre (Prod bzw. Prod-Staging zum Verifizieren der Prod-Routen) → Produktiv-Umgebung der VU; api-fachtest und api-fachtest-pre → Test-Umgebung der VU. Dieses Default-Mapping liegt in der Backend-Konfiguration je Environment (api.togethercca.com/config/forward.d/{env}), nicht in der URL. Der Suffix wird nur gesetzt, wenn ein Caller bewusst von diesem Default abweicht (z.B. ÖAMTC testet aus Prod gegen Generali-Maint). Hängt am target, nicht am service. Unsere eigene Umgebung kommt nie in den Pfad.
serviceContract-Namekleingeschrieben, aus der Registry
releaseCCA-Release-Keynur unter /products/cca/, siehe 2.3
pathRest an den DownstreamEine service-eigene Version (z.B. boa-api/v1.0/...) ist Teil von path.

Beispiele:

URLBedeutung
/partners/vig/soagfx/...VIG ruft unseren SOAGFX
/partners/generali/gfweitergabe/...Generali ruft unsere GF-Weitergabe
/partners/vig/kooperation/donau/...VIG Cooperative Processing; die Marke (Donau/WSTV) ist Teil des Service-Pfads, kein target – kooperation ist unser Service, ein Client für beide Marken
/customers/oeamtc/generali/omds3/...ÖAMTC → Generali OMDS3 über unseren Integration-Service
/customers/oeamtc/generali-maint/omds3/...dito, Generali-Wartungsumgebung
/customers/oeamtc/generali-maint/evpconnect/...dito, EVP-Connect
/customers/efs/boa-api/v1.0/kfz/...EFS ruft die BoaApi; v1.0 ist die Version der BoaApi selbst, Teil von path
/customers/oeamtc/scim/UsersEntra-Provisioning des ÖAMTC. Entra ist Transport, nicht Caller; die Route mappt oeamtc fest auf die Entra-Tenant-Id (/scim/{tenantId}/Users) – der einzige Fall, in dem das Gateway den Mandanten technisch erzwingt statt ihn dem Caller zu glauben. Analog /partners/{vu}/scim.
/products/cca/2026-8/generali/omds3/...CCA Release 2026-8 → Generali OMDS3
/products/cca/2026-8/autopreisspiegel/...CCA Release 2026-8 → unser Autopreisspiegel
/products/boa-api/uniqa/omds3/...BoaApi → UNIQA OMDS3
/3rd-party/cheggnet/donau/omds3/...Vergleichsportal → Donau Kfz-Tarif; die Makler-Organisation kommt aus dem User-Token
/3rd-party/vers-admin-m/boa-api/v1.0/...Maklersoftware ruft die BoaApi fĂĽr den eingeloggten Makler

2.3 Versionierung: Service-Contract vs. Client-Release​

(a) Contract-Version – optional, Sache des Service. Das Gateway versioniert nicht automatisch und erzwingt kein Versions-Segment. Ob und wie ein Service seinen Contract versioniert (eigenes Pfadsegment wie boa-api/v1.0/..., Version im Payload wie bei OMDS3, oder gar nicht), entscheidet der Service – bei VU-Services liegt das ohnehin nicht in unserer Hand. Eine service-eigene Version ist aus Sicht des Gateways Teil von {**path}. Ein alter Contract-Stand bleibt erreichbar, solange ein Client ihn nutzt (bei Bedarf als eingefrorenes Parallel-Deployment, siehe (b) Punkt 3).

(b) Client-Release-Key {release} – ausschließlich für products/cca. Das Gateway-eigene Versionierungsinstrument für Caller, die nicht on-demand ausgerollt werden können. Service-eigene Versionen im Pfad bleiben davon unberührt.

/products/cca/{release}/[{target}[-{targetEnv}]/]{service}/{**path}
release = YYYY-R (Regex-Constraint ^\d{4}-\d{1,2}$ ist Pflicht)

Begründung: Der Release-Key ist keine API-Version, sondern ein Capability-Identifier des Clients. Er sagt: "Dieser Request kommt von einem Client mit genau diesem eingefrorenen Verhalten." Im Gegensatz zu einer Contract-Version des Service muss er nicht vorausschauend vergeben werden – jedes Release ist automatisch unterscheidbar. Damit kann nachträglich, wenn eine VU einen Breaking Change einbaut, für genau die betroffenen Releases anders geroutet werden.

Regeln fĂĽr den Release-Key:

  1. Die Default-Route ist ein Template. Ein neues CCA-Release braucht keine Gateway-Änderung.
    forward /products/cca/{release:regex(^\d{4}-\d{1,2}$)}/generali/omds3/{**remainder} { ... }
  2. Override-Routen sind die Ausnahme und liegen mit order -1 vor dem Template. Sie dienen ausschließlich der Kompatibilität, nie für Fachlogik oder Feature-Flags.
    forward /products/cca/{release:regex(^(2025-.*|2026-[1-8])$)}/generali/omds3/{**remainder} {
    order -1
    # Ticket #….: Generali OMDS3 Contract-Break am YYYY-MM-DD; Sunset: wenn 2026-8 aus dem Support fällt
    ...
    }
    Jede Override-Route trägt im Kommentar Ticket, Grund und Sunset-Kriterium.
  3. Das Gateway routet, es übersetzt nicht. Hinter einer Override-Route steht ein Ziel, das den alten Contract bedient. Standard-Vorgehen: den Integration-Service-Stand, der mit dem alten VU-Contract funktioniert hat, als eingefrorenes Parallel-Deployment behalten (z.B. tis.partner.generaliIntegration-2026-8) und die Override-Route dorthin zeigen. Nicht rückwärts Compat-Code in den laufenden Service bauen.
  4. Reihenfolge cca/{release}/{target}/{service}: Release direkt nach dem Produkt, damit Overrides per Prefix greifen ("alles, was 2026-8 tut").
  5. Pfad, nicht Header: der Key ist damit in IIS-/Gateway-Logs sichtbar, mit dem Route-Dry-Run testbar und in jedem Proxy routbar.
  6. Das gilt auch für unsere eigenen Services (/products/cca/{release}/autopreisspiegel). Nebeneffekt: pro Release ist auswertbar, welche Installationen noch welchen Stand fahren – Grundlage für Sunset-Entscheidungen.

Entscheidungsbaum bei einer Änderung auf VU-Seite:

VU ändert …Maßnahme
nur Host/URLBackend-Destination am Gateway bzw. im Integration-Service ändern. Keine Override-Route.
den Contract (Breaking)Integration-Service-Stand einfrieren (Parallel-Deployment) → Override-Route für betroffene Releases → Default-Route zeigt auf den neuen Stand. Für Caller, die on-demand deployen: Versionierung nach dem Mechanismus des Service; der alte Stand bleibt erreichbar, solange ein Client ihn nutzt.

2.4 Tenant-Binding​

Das caller-Segment ist nicht nur Namensraum, sondern wird erzwungen: Das Gateway prüft, dass das Segment zur Identität des Tokens (Client-Id bzw. Tenant-Claim) passt. Ein Token von Tenant A darf auf /customers/b/... nicht autorisieren, auch wenn beide denselben Scope besitzen.

Konsequenzen:

  • Per-Tenant-URLs sind damit ein belastbarer SchlĂĽssel fĂĽr Rate-Limiting, Log-Dimensionen und spätere Divergenz pro Tenant.
  • Unter /3rd-party/ bindet das Segment an die App (Client-Id); die Makler-Organisation aus dem User-Token wird als zweite Dimension geloggt und kann fĂĽr Rate-Limits pro BĂĽro verwendet werden.
  • Routen fĂĽr gleichartige Tenants können zu einer Regex-Route kollabieren (/customers/{customer:regex(^(efs|versfinanz)$)}/boa-api/...), statt pro Tenant kopiert zu werden.
  • Das caller-Segment wird als Header an den Downstream weitergereicht (z.B. X-Tis-Tenant), damit auch der Downstream den Mandanten kennt.
  • Offene Regex-Segmente (regex([a-zA-Z]+)) ohne Binding sind nicht zulässig.

2.5 Weitere Regeln​

  • Kein Catch-All direkt unter {caller}. Immer {caller}/{service}/.... Alles, was nicht explizit geroutet ist, ist nicht erreichbar (Default-Deny).
  • Jede Route hat scope oder ein explizites anonymous mit BegrĂĽndung im Kommentar.
  • Health einmal pro Backend, nicht pro Tenant.
  • Namensraum-Literale im Plural: /products/, /partners/, /customers/, /3rd-party/. Die heute produktiven /partner/*-Routen bleiben als deprecated Alias auf dieselben Backends bestehen, bis kein Client sie mehr nutzt.
  • Maschinen-Routen ausschlieĂźlich auf api.togethercca.com. Auf www/b2b werden keine neuen API-Routen angelegt.
  • Legacy-Routen (/services/*, /omds3services/*, direkte App-Namen) bleiben als Aliase auf dasselbe Backend bestehen, solange ein unterstĂĽtztes Release sie nutzt. Sie tragen im Kommentar deprecated + Sunset-Kriterium und werden per Route-Telemetrie ĂĽberwacht; Abbau erst bei nachweislich null Nutzung.
  • Jede Umgebungs-Variante (-maint, -test) ist eine eigene Route auf ein eigenes Backend; kein Umschalten per Query-Parameter oder Header. Die Route ohne Suffix ist der Regelfall; Suffix-Routen sind die Ausnahme und existieren nur, wo ein Caller sie tatsächlich braucht.

2.6 Registry​

Ein Slug je Organisation/Produkt/Service, einheitlich verwendet in Route, Scope-Name, Tenant-Claim, Log-Dimension und Rate-Limit-Key. Die vollständige Registry inkl. Zuordnung zu Identity-Clients, Scopes, Backends und Bereinigungsliste steht in api-gateway-route-registry.md. Hier nur die Slug-Übersicht:

/products/: cca, boa-api, boabot

/partners/: vig (Konzern-Slug; Donau/WSTV werden ĂĽber Scope bzw. Service-Pfad unterschieden, nicht als Caller), generali, ergo, uniqa, riskine

/customers/: oeamtc, greco, ovb, efs, efm, versfinanz, sls, wefox, aon, arisecur, avag, cbn, igv, dvm, afb, gundo, pth, sivag, oebv, mercedes, toyota-im, rci, sepp-schinner

/3rd-party/: basic-systems, vers-admin-a, vers-admin-m, onlineordner, proagent, varias, vera, insureit, finova, novumrgi, krankenprofi, courtagecontrol, servers, insurapp, authentic, promakler, cheggnet, durchblicker, check24, kapdion

Targets (VU-Systeme): uniqa, generali, donau, wstv, allianz, hdi, grawe, vav, zuerich, wuestenrot, muki, merkur

Services – unsere: soagfx, soaomdsx, gfweitergabe, cads, cads-rest, gfapi, boa-api, accounts, kooperation, autopreisspiegel, scim, userabgleich, omds3engine, wrka, eop-callback, esign, deeplink, omds3-bestand

Services – VU (mit target): omds3, evpconnect

Tenant-Binding erfolgt ĂĽber einen Client-Claim tis_tenant in tis.identity (Details und offene Punkte: api-gateway-route-registry.md, Abschnitte 2 und 8).

3. Migration​

  1. ForwardFile-DSL erweitern: Tenant-Binding (caller ↔ Token-Identität) und Weitergabe als Header.

  2. Convention-Test in api.togethercca.com/src/Tests: parst alle .forward-Dateien und prĂĽft Grammatik, Registry-Slugs, Pflicht-Regex am release-Segment, vorhandene ScopedPolicy je scope, kein Catch-All unter {caller}, Sunset-Kommentar bei deprecated/Override-Routen.

  3. Bestehende Gateway-Routen auf die Grammatik bringen (Tenant-Duplikate zusammenziehen, Slugs vereinheitlichen). Alte Pfade bleiben als deprecated Aliase.

  4. API-Traffic von www/b2b auf das Gateway ziehen, direkt ins Zielformat (nicht als weiterer Legacy-Alias). Betroffen:

    • www: omds3services/{uniqa,donau,wstv,vig,muki,gli,tis}/*, tis.partner.*Integration/*, cads.extern, cads-api, gfapi, tis.gf.boaapi, tis.identity.ovbselfservice, tis.anmeldung.api, volltextsuche.*.import, omds3engine/integration/configuration
    • b2b: axis2/services/SOAGFX_2_0, SOAOMDSX, GFWeitergabe, vigo/{wstv,donau}/*, cads-api, UCL, smr5, tis2go-TISIntegrationService

    Da diese Routen am alten Edge anonym sind, ist je Partner ein Onboarding-Schritt nötig (Scope-Policy definieren, Client erhält Token). Die OMDS3-Portale besitzen bereits OAuth-Clients.

  5. Die Helicon-Configs unter Versionskontrolle stellen; sie sind die Referenz dafür, was heute tatsächlich exponiert ist.

  6. Nach Abschluss: www/b2b sind Browser-only.

4. Konsequenzen​

Positiv

  • Ă–ffentliche URLs sind von Deploy-Namen, Hosts und VU-Umgebungen entkoppelt.
  • Auf Breaking Changes einer VU kann nachträglich und gezielt pro CCA-Release reagiert werden, ohne CCA ausrollen zu mĂĽssen.
  • Tenant-URLs sind belastbar (erzwungen) und damit Grundlage fĂĽr Rate-Limit, Telemetrie und Auswertung des Release-Stands im Feld.
  • Default-Deny am Edge statt anonymer Durchleitung.

Negativ / Risiken

  • Override-Routen und eingefrorene Parallel-Deployments können sich ansammeln. GegenmaĂźnahme: Pflicht-Sunset je Override, Convention-Test, regelmäßige Auswertung der Release-Telemetrie.
  • Range-AusdrĂĽcke ĂĽber Releases ("alle ≤ 2026-8") sind nur als Regex-Alternation ausdrĂĽckbar. Akzeptiert; eine Custom-Constraint wird erst eingefĂĽhrt, wenn das wiederholt Aufwand erzeugt.
  • Migration von www/b2b erfordert Partner-Koordination (Token-Onboarding) und ist damit nicht rein technisch terminierbar.

5. Offene Punkte​

  • Vierter Namensraum /3rd-party/ – Vorschlag, noch nicht entschieden. Alternative wäre, Apps unter /customers/ mit App als Caller zu fĂĽhren (kein eigener Namensraum). Namenskandidaten, falls 3rd-party (Ziffer + Bindestrich) stört: software kollidiert mit products, apps ist zu schwach.
  • Grenzfälle nach Token-Kriterium prĂĽfen: wefox, ovb.together-api.client, promakler, servers, avag.
  • MĂĽssen interne Caller (BoaApi auf tisapp01) ĂĽber den öffentlichen Edge-Gateway zur VU, oder rufen sie den Integration-Service direkt intern auf? Wenn ĂĽber das Gateway, dann bewusst wegen einheitlicher Auth/Telemetrie.
  • Umsetzung des Tenant-Bindings in Tis.Hosting.Extensions.RequestForwarding.ForwardFile (Direktive, Claim-Quelle).
  • Zuordnung von OVB (customers oder partner) anhand der Regel in 2.1 festziehen.