API-Versionierungsschema aus der URL erkennen

Öffentliche HTTP-APIs kündigen ihren Versionierungsstil an unterschiedlichen Stellen an: als Pfadsegment wie /v2/, als Query-String wie ? api_version=2 oder gar nicht in der URL, wenn Clients Accept oder benutzerdefinierte Header senden sollen. Integrationen, Gateways, SDK-Generatoren und Dokumentations-Crawler brauchen eine einzige deterministische Antwort darauf, welches Schema eine Endpoint-URL verwendet und welches Versionstoken sie trägt. Diese Fähigkeit akzeptiert eine absolute API-URL, lehnt Zeichenketten ab, die keine wohlgeformten http- oder https-URLs sind, und klassifiziert das Schema als path_based, query_param oder header_implied. Enthalten weder Pfad noch Query einen konventionellen Versionsmarker, ist das Ergebnis header_implied mit has_version false und signalisiert, dass die Versionierung relativ zur URL außerhalb des Bandes liegt.

Wie pfadbasierte, Query- und headerimplizite Schemata unterschieden werden

Pfadbasierte Versionierung ist die vorherrschende REST-Konvention: Ein Segment wie v1, v2 oder v1.2.3 erscheint im pathname, oft unter /api/ oder als erstes sinnvolles Segment nach dem Host. Dieser Detektor durchläuft Pfadsegmente von links nach rechts und behandelt eine groß-/kleinschreibungsunabhängige Übereinstimmung von v gefolgt von einer numerischen Version als path_based; er liefert den numerischen Teil als version und das Originalsegment als version_raw mit location auf diesem Segment (zum Beispiel /v2). Query-Parameter-Versionierung legt das Token im Suchstring unter gängigen Schlüsseln ab: version, api_version, api-version, apiversion, ver und v. Würden Pfad und Query treffend sein, hat path_based Vorrang, weil öffentliche REST-Dokumentation das Pfadsegment fast immer als Primärvertrag und die Query als sekundäre Überschreibung behandelt. Liefert keine Quelle eine Version, ist das Schema header_implied: Die URL allein kodiert keine Version, was bei modernen APIs meist Accept: application/vnd.example.v1+json, einen benutzerdefinierten X-API-Version-Header oder eine unversionierte Oberfläche bedeutet.

Eingabevertrag, Erfolgsnutzlast und Validierungsfehler

Beispiel: https://api.example.com/users? Senden Sie per POST einen JSON-Body mit einem einzigen Pflicht-Stringfeld namens url. Der Wert muss eine wohlgeformte absolute URL mit Schema http oder https sein; relative Pfade, Hostnamen ohne Schema, leere Zeichenketten, Nicht-String-Typen und andere Protokolle wie ftp oder mailto scheitern mit invalid_input und werden nicht berechnet. Bei Erfolg enthält die Antwort immer die zurückgegebene url, scheme (path_based, query_param oder header_implied), has_version (boolesch), path (pathname) und host. Ist has_version true, enthält die Nutzlast auch version (normalisiertes Token), version_raw (wie in der URL gefunden) und location (ein kurzer Zeiger wie /v2 oder ? api_version=2). Bei query_param-Ergebnissen speichert param_name die Originalschreibweise des Schlüssels in der URL. Optionale Felder werden weggelassen statt auf null gesetzt, wenn has_version false ist, damit der Vertrag DOM-sicher und leicht zu rendern bleibt. Beispiel: https://api.example.com/v2/users ergibt scheme path_based, version 2 und location /v2. api_version=2 ergibt scheme query_param, version 2 und param_name api_version. Beispiel: https://api.example.com/users ohne Versionsmarker ergibt scheme header_implied und has_version false. Nutzen Sie das kostenlose Browser-Werkzeug für Einzelprüfungen oder die API zu $0.002 pro erfolgreichem Element, wenn Sie Endpoints aus einem Inventar oder OpenAPI-Crawl massenhaft klassifizieren.

Wo die Erkennung der URL-Versionierung ihren Nutzen zeigt

Plattformteams inventarisieren Hunderte interner und Partner-Basis-URLs und brauchen ein einheitliches Label, bevor Verkehr über ein Gateway mit Deprecationsfenstern geroutet wird. Fehlgeschlagene Validierung wird nicht berechnet. SDK-Generatoren und Client-Scaffolding-Werkzeuge verzweigen Vorlagen danach, ob der Server /vN/ im Pfad, ein Query-Flag oder nur Header-Versionierung erwartet; ein reiner Klassifikator vermeidet brüchige Ad-hoc-Regexe quer durch Repositories. Dokumentationsseiten und API-Marktplätze zeigen Badges zum Versionierungsstil neben jedem Eintrag; die Speisung mit diesem Endpoint hält Marketingtext und live URL-Form im Einklang. Sicherheits- und Compliance-Reviews fragen oft, ob Produktionshosts noch unversionierte Pfade oder gemischte Schemata freigeben, die Rollouts brechender Änderungen erschweren; der Export von scheme und has_version in eine Tabelle beantwortet das in einem Durchgang. CI-Jobs können einen Pull Request ablehnen, wenn eine neu hinzugefügte Service-Basis-URL still von path_based auf header_implied wechselt, ohne ADR. Weil die Implementierung reines Parse der Stufe A ist, kostet jeder erfolgreiche Aufruf den veröffentlichten Basispreis $0.002, ohne Modell-Token und ohne Abruf des Zielhosts.