Detect API versioning scheme from URL

Public HTTP APIs advertise their versioning style in different places: a path segment such as /v2/, a query string such as ? api_version=2, or nowhere in the URL at all when clients are expected to send Accept or custom headers. Integrations, gateways, SDK generators, and documentation crawlers all need a single deterministic answer for which scheme a given endpoint URL uses and which version token it carries. This capability accepts one absolute API URL, rejects strings that are not well-formed http or https URLs, and classifies the versioning scheme as path_based, query_param, or header_implied. When neither path nor query contains a conventional version marker, the result is header_implied with has_version false, signalling that versioning is conventionally out-of-band relative to the URL.

How path, query, and header-implied schemes are distinguished

Keys are matched case-insensitively; the first key in that fixed priority list that has a non-empty value wins, so results stay stable regardless of parameter order in the original URL. Values may look like 2, v2, or 1.0.0; a leading v is stripped for the normalized version field when the token is purely numeric with optional dots. Free-form alphanumerical tokens such as beta or 2024-01-01 are kept as-is when they match a safe identifier pattern. The detector never performs network I/O and never invents a version from hostnames alone. Path-based versioning is the dominant REST convention: a segment such as v1, v2, or v1.2.3 appears in the pathname, often under /api/ or as the first meaningful segment after the host. This detector walks path segments left to right and treats a case-insensitive match of v followed by a numeric version as path_based, returning the numeric part as version and the original segment as version_raw with location set to that segment (for example /v2). It also recognizes the two-segment form version/1 or versions/2.0 so documentation-style routes still classify correctly. Query-param versioning places the token in the search string under common keys including version, api_version, api-version, apiversion, ver, and v. When both path and query would match, path_based takes priority because public REST documentation almost always treats the path segment as the primary contract and the query string as a secondary override. When neither source yields a version, the scheme is header_implied: the URL alone does not encode a version, which in modern APIs usually means Accept: application/vnd.example.v1+json, a custom X-API-Version header, or an unversioned surface.

Input contract, success payload, and validation errors

Example: https://api.example.com/users? POST a JSON body with a single required string field named url. The value must be a well-formed absolute URL using the http or https scheme; relative paths, bare hostnames without a scheme, empty strings, non-string types, and other protocols such as ftp or mailto fail with invalid_input and are not billed. On success the response always includes the echoed url, scheme (one of path_based, query_param, or header_implied), has_version (boolean), path (pathname), and host. When has_version is true the payload also includes version (normalized token), version_raw (as found in the URL), and location (a short pointer such as /v2 or ? api_version=2). For query_param results, param_name records the original key spelling from the URL. Optional fields are omitted rather than set to null when has_version is false, keeping the contract DOM-safe and easy to render. Example: https://api.example.com/v2/users yields scheme path_based, version 2, and location /v2. api_version=2 yields scheme query_param, version 2, and param_name api_version. Example: https://api.example.com/users with no version markers yields scheme header_implied and has_version false. Use the free browser tool for one-off inspection, or the API at $0.002 per successful item when you classify endpoints in bulk from an inventory file or OpenAPI crawl.

Where URL versioning detection earns its keep

Platform teams inventory hundreds of internal and partner base URLs and need a consistent label before routing traffic through a gateway that enforces deprecation windows. Failed validation does not consume balance. SDK generators and client scaffolding tools branch templates on whether the server expects /vN/ in the path, a query flag, or header-only versioning, and a pure classifier avoids brittle ad-hoc regexes scattered across repositories. Documentation sites and API marketplaces show badges for versioning style next to each listing; feeding them this endpoint keeps marketing copy aligned with the live URL shape. Security and compliance reviews often ask whether production hosts still expose unversioned paths or mixed schemes that complicate rollout of breaking changes; exporting scheme and has_version into a spreadsheet answers that in one pass. CI jobs can fail a pull request when a newly added service base URL silently switches from path_based to header_implied without an ADR.