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), alletis.partner.*Integration, CCA
| Status | Vorgeschlagen (Draft) |
| Dokumente | Registry · Cheat Sheet (HTML) · Gateway-Repo api.togethercca.com |
| Gilt fĂĽr | alle Maschinen-Schnittstellen, die wir oder unsere Partner ĂĽber die TOGETHER-Plattform anbieten |
| Gilt nicht fĂĽr | Routen 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:
| # | Namensraum | Der Caller ist … | Beispiele | Gehö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-Principal | vig, generali, uniqa, ergo, riskine | Software 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 gebunden | oeamtc, greco, ovb, efs, versfinanz, oebv | Software, 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üros | vers-admin-m, onlineordner, basic-systems, cheggnet, durchblicker | unsere eigenen Produkte, auch wenn fremdentwickelt → /products/ |
Abgrenzungskriterium (Vorschlag, zu prüfen): der Kontext des Tokens, nicht die Geschäftsbeziehung oder der Name.
| Kontext | Token | Beispiel | |
|---|---|---|---|
/partners/ | System-Kontext – das fremde System selbst ist der Akteur, kein Makler-Principal | client_credentials / IP-Filter, oder Token-Exchange mit delegation_scope: together:all-users | Generali ändert einen Geschäftsfall; VIG holt CADS-Daten ab |
/customers/ | Makler-Büro-Kontext, eine Organisation – der Client selbst ist an die Organisation gebunden | Client-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 Makler | User-Token (authorization_code) aus einer Software, die n Büros nutzen | OnlineOrdner 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).
| Segment | Bedeutung | Regeln |
|---|---|---|
caller | wer ruft | Slug aus der Registry (Abschnitt 2.6). Muss zur Identität des Tokens passen (Abschnitt 2.4). |
target | VU, deren Service über unseren Integration-Service erreicht wird | optional. Vorhanden ⇔ der Service gehört einer VU (Pass-Through). Fehlt ⇔ der Service ist unser eigener. |
targetEnv | Abweichung von der Default-Umgebung der VU | optional, 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. |
service | Contract-Name | kleingeschrieben, aus der Registry |
release | CCA-Release-Key | nur unter /products/cca/, siehe 2.3 |
path | Rest an den Downstream | Eine service-eigene Version (z.B. boa-api/v1.0/...) ist Teil von path. |
Beispiele:
| URL | Bedeutung |
|---|---|
/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/Users | Entra-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:
- 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} { ... } - Override-Routen sind die Ausnahme und liegen mit
order -1vor dem Template. Sie dienen ausschließlich der Kompatibilität, nie für Fachlogik oder Feature-Flags.Jede Override-Route trägt im Kommentar Ticket, Grund und Sunset-Kriterium.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
...
} - 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. - Reihenfolge
cca/{release}/{target}/{service}: Release direkt nach dem Produkt, damit Overrides per Prefix greifen ("alles, was 2026-8 tut"). - Pfad, nicht Header: der Key ist damit in IIS-/Gateway-Logs sichtbar, mit dem Route-Dry-Run testbar und in jedem Proxy routbar.
- 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/URL | Backend-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
scopeoder ein explizitesanonymousmit 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. Aufwww/b2bwerden 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 Kommentardeprecated+ 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​
-
ForwardFile-DSL erweitern: Tenant-Binding (
caller↔ Token-Identität) und Weitergabe als Header. -
Convention-Test in
api.togethercca.com/src/Tests: parst alle.forward-Dateien und prĂĽft Grammatik, Registry-Slugs, Pflicht-Regex amrelease-Segment, vorhandene ScopedPolicy jescope, kein Catch-All unter{caller}, Sunset-Kommentar beideprecated/Override-Routen. -
Bestehende Gateway-Routen auf die Grammatik bringen (Tenant-Duplikate zusammenziehen, Slugs vereinheitlichen). Alte Pfade bleiben als deprecated Aliase.
-
API-Traffic von
www/b2bauf 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/configurationb2b: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.
-
Die Helicon-Configs unter Versionskontrolle stellen; sie sind die Referenz dafür, was heute tatsächlich exponiert ist.
-
Nach Abschluss:
www/b2bsind 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/b2berfordert 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, falls3rd-party(Ziffer + Bindestrich) stört:softwarekollidiert mitproducts,appsist 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 (
customersoderpartner) anhand der Regel in 2.1 festziehen.