Rilevare lo schema di versionamento API dall'URL

Le API HTTP pubbliche annunciano lo stile di versionamento in punti diversi: un segmento di percorso come /v2/, una query string come ? api_version=2, oppure in nessun punto dell'URL quando i client devono inviare Accept o intestazioni personalizzate. Integrazioni, gateway, generatori di SDK e crawler di documentazione necessitano di una risposta deterministica unica su quale schema usi un endpoint e quale token di versione porti. Questa capacità accetta un URL assoluto di API, rifiuta le stringhe che non sono URL http o https ben formati e classifica lo schema come path_based, query_param o header_implied. Se né il percorso né la query contengono un marcatore convenzionale, il risultato è header_implied con has_version false, a indicare che il versionamento è fuori banda rispetto all'URL.

Come si distinguono gli schemi per percorso, query e intestazione implicita

Il versionamento basato sul percorso è la convenzione REST dominante: un segmento come v1, v2 o v1.2.3 compare nel pathname, spesso sotto /api/ o come primo segmento significativo dopo l'host. Questo rilevatore scorre i segmenti da sinistra a destra e tratta una corrispondenza, senza distinzione di maiuscole, di v seguita da una versione numerica come path_based, restituendo la parte numerica come version e il segmento originale come version_raw con location impostata su quel segmento (ad esempio /v2). Il versionamento tramite parametro di query colloca il token nella stringa di ricerca sotto chiavi comuni: version, api_version, api-version, apiversion, ver e v. Quando percorso e query corrisponderebbero entrambi, path_based ha priorità perché la documentazione REST pubblica tratta quasi sempre il segmento di percorso come contratto primario e la query come override secondario. Se nessuna fonte fornisce una versione, lo schema è header_implied: l'URL da solo non codifica una versione, il che nelle API moderne di solito significa Accept: application/vnd.example.v1+json, un'intestazione X-API-Version personalizzata o una superficie non versionata.

Contratto di ingresso, payload di successo ed errori di validazione

Esempio: https://api.example.com/users? Invii con POST un corpo JSON con un unico campo stringa obbligatorio denominato url. Il valore deve essere un URL assoluto ben formato con schema http o https; percorsi relativi, hostname senza schema, stringhe vuote, tipi non stringa e altri protocolli come ftp o mailto falliscono con invalid_input e non vengono addebitati. In caso di successo la risposta include sempre l'url ecoata, scheme (path_based, query_param o header_implied), has_version (booleano), path (pathname) e host. Quando has_version è true, il payload include anche version (token normalizzato), version_raw (come nell'URL) e location (un puntatore breve come /v2 o ? api_version=2). Per i risultati query_param, param_name registra l'ortografia originale della chiave nell'URL. I campi opzionali vengono omessi anziché impostati a null quando has_version è false, mantenendo il contratto sicuro per il DOM e facile da renderizzare. Esempio: https://api.example.com/v2/users produce scheme path_based, version 2 e location /v2. api_version=2 produce scheme query_param, version 2 e param_name api_version. Esempio: https://api.example.com/users senza marcatori di versione produce scheme header_implied e has_version false. Usi lo strumento gratuito del browser per un'ispezione puntuale, oppure l'API a $0.002 per elemento riuscito quando classifica endpoint in blocco da un inventario o da un crawl OpenAPI.

Dove la rilevazione del versionamento nell'URL ripaga

I team di piattaforma inventariano centinaia di URL di base interni e dei partner e necessitano di un'etichetta coerente prima di instradare il traffico attraverso un gateway che impone finestre di deprecazione. La validazione fallita non consuma saldo. I generatori di SDK e gli strumenti di scaffolding dei client ramificano i template a seconda che il server attenda /vN/ nel percorso, un flag di query o solo versionamento tramite intestazione; un classificatore puro evita regex fragili sparse nei repository. I siti di documentazione e i marketplace di API mostrano badge sullo stile di versionamento accanto a ogni scheda; alimentarli con questo endpoint allinea il testo di marketing alla forma reale dell'URL. Le revisioni di sicurezza e conformità chiedono spesso se gli host di produzione espongono ancora percorsi non versionati o schemi misti che complicano il rilascio di modifiche incompatibili; esportare scheme e has_version in un foglio risponde in un solo passaggio. I job CI possono far fallire una pull request quando l'URL di base di un servizio appena aggiunto passa silenziosamente da path_based a header_implied senza un ADR. Poiché l'implementazione è pure parse di tier A, ogni chiamata riuscita costa il prezzo base pubblicato $0.002, senza token di modello e senza fetch dell'host di destinazione.