WHATWG URL API: Safely Parse URLs, Not Strings

WHY IT EXISTS: URLs seem simple but are complex. They have many parts, tricky encoding rules, and numerous edge cases. Manually parsing them with string manipulation or regular expressions is a common source of bugs and security vulnerabilities. A standardized, robust parser is needed to handle this complexity reliably across different environments, like browsers and servers.

THE MENTAL MODEL: Think of the WHATWG URL API as JSON.parse for URLs. It takes a raw URL string and converts it into a structured URL object with properties you can safely access and modify, like hostname, pathname, and searchParams. You no longer work with a fragile string; you work with a predictable object.

HOW IT WORKS: You create a new URL object by passing a URL string to its constructor: const myURL = new URL('https://example.com/path?query=1#hash');. This returns an object with properties like myURL.protocol ('https:'), myURL.hostname ('example.com'), and myURL.pathname ('/path'). Critically, it includes a myURL.searchParams property. This is a URLSearchParams object with methods like .get(), .set(), and .append() for safely manipulating the query string without manual encoding. To get the full, updated URL string back, you access the myURL.href property.

WHEN TO USE IT: Use this API whenever you receive, process, or construct a URL in a Node.js application. It's ideal for routing in web frameworks, validating redirect URLs, building URLs for API client requests, and extracting query parameters from an incoming request URL. It is the modern, correct, and browser-compatible way to handle URLs.

WHEN NOT TO USE IT: The legacy url.parse() API should be avoided in all new code. The WHATWG API is the standard. If you are on an ancient, unsupported version of Node.js, you may be forced to use the legacy API, but the goal should be to upgrade. For extremely simple, internal, and predictable string building where no user input is involved, it might be slight overkill, but using it is still a safer habit.

ONE CANONICAL EXAMPLE: Imagine you're building a paginated API endpoint and need to construct the "next page" link. Instead of string manipulation, you can do this: const requestURL = new URL('https://api.example.com/v1/items?page=2&limit=10'); const currentPage = Number(requestURL.searchParams.get('page')); requestURL.searchParams.set('page', currentPage + 1); const nextPageURL = requestURL.href; This safely produces "https://api.example.com/v1/items?page=3&limit=10" without fragile string replacement.