Détecter le schéma de versionnement d'API via l'URL

Les API HTTP publiques annoncent leur style de versionnement à des endroits différents : un segment de chemin comme /v2/, une chaîne de requête comme ? api_version=2, ou nulle part dans l'URL lorsque les clients doivent envoyer Accept ou des en-têtes personnalisés. Intégrations, passerelles, générateurs de SDK et crawlers de documentation ont besoin d'une réponse déterministe unique sur le schéma qu'utilise un endpoint et le jeton de version qu'il porte. Cette capacité accepte une URL d'API absolue, rejette les chaînes qui ne sont pas des URL http ou https bien formées, et classe le schéma en path_based, query_param ou header_implied. Si ni le chemin ni la requête ne contiennent de marqueur conventionnel, le résultat est header_implied avec has_version false, indiquant que le versionnement est hors bande par rapport à l'URL.

Comment distinguer les schémas par chemin, requête et en-tête implicite

Le versionnement par chemin est la convention REST dominante : un segment comme v1, v2 ou v1.2.3 apparaît dans le pathname, souvent sous /api/ ou comme premier segment significatif après l'hôte. Ce détecteur parcourt les segments de gauche à droite et traite une correspondance, sans distinction de casse, de v suivie d'une version numérique comme path_based, en renvoyant la partie numérique comme version et le segment d'origine comme version_raw avec location pointant vers ce segment (par exemple /v2). Le versionnement par paramètre de requête place le jeton dans la chaîne de recherche sous des clés courantes : version, api_version, api-version, apiversion, ver et v. Lorsque chemin et requête correspondraient tous deux, path_based a la priorité car la documentation REST publique traite presque toujours le segment de chemin comme contrat principal et la requête comme surcharge secondaire. Si aucune source ne fournit de version, le schéma est header_implied : l'URL seule n'encode pas de version, ce qui dans les API modernes signifie souvent Accept: application/vnd.example.v1+json, un en-tête X-API-Version personnalisé ou une surface non versionnée.

Contrat d'entrée, charge utile de succès et erreurs de validation

Exemple : https://api.example.com/users? Envoyez en POST un corps JSON avec un unique champ chaîne obligatoire nommé url. La valeur doit être une URL absolue bien formée avec le schéma http ou https ; les chemins relatifs, les noms d'hôte sans schéma, les chaînes vides, les types non chaîne et d'autres protocoles comme ftp ou mailto échouent avec invalid_input et ne sont pas facturés. En cas de succès, la réponse inclut toujours l'url renvoyée en écho, scheme (path_based, query_param ou header_implied), has_version (booléen), path (pathname) et host. Lorsque has_version vaut true, la charge inclut aussi version (jeton normalisé), version_raw (tel que trouvé dans l'URL) et location (un pointeur court comme /v2 ou ? api_version=2). Pour les résultats query_param, param_name enregistre l'orthographe d'origine de la clé dans l'URL. Les champs optionnels sont omis plutôt que mis à null lorsque has_version est false, ce qui garde le contrat sûr pour le DOM et simple à afficher. Exemple : https://api.example.com/v2/users donne scheme path_based, version 2 et location /v2. api_version=2 donne scheme query_param, version 2 et param_name api_version. Exemple : https://api.example.com/users sans marqueurs de version donne scheme header_implied et has_version false. Utilisez l'outil gratuit du navigateur pour une inspection ponctuelle, ou l'API à $0.002 par élément réussi lorsque vous classifiez des endpoints en masse depuis un inventaire ou un crawl OpenAPI.

Où la détection du versionnement d'URL apporte de la valeur

Les équipes plateforme inventorient des centaines d'URL de base internes et partenaires et ont besoin d'une étiquette cohérente avant d'acheminer le trafic via une passerelle qui impose des fenêtres de dépréciation. Une validation échouée ne consomme pas le solde. Les générateurs de SDK et les outils d'échafaudage client branchent des modèles selon que le serveur attend /vN/ dans le chemin, un indicateur de requête ou un versionnement uniquement par en-tête ; un classifieur pur évite les expressions rationnelles fragiles dispersées dans les dépôts. Les sites de documentation et les places de marché d'API affichent des badges de style de versionnement à côté de chaque fiche ; les alimenter avec ce point de terminaison aligne le texte marketing sur la forme réelle de l'URL. Les revues de sécurité et de conformité demandent souvent si les hôtes de production exposent encore des chemins non versionnés ou des schémas mixtes qui compliquent le déploiement de changements incompatibles ; exporter scheme et has_version vers un tableur répond en un seul passage. Les tâches CI peuvent faire échouer une demande de fusion lorsqu'une URL de base de service nouvellement ajoutée passe silencieusement de path_based à header_implied sans ADR. Comme l'implémentation est purement parse de niveau A, chaque appel réussi coûte le prix de base publié $0.002, sans jetons de modèle ni récupération du hôte cible.