Parsing URLs with the URL API

The URL constructor takes a string and gives you an object with the parts already broken out. You read them from named properties rather than parsing the string yourself.

const url = new URL("https://user:[email protected]:8443/docs/guide?tab=api&page=2#section");

console.log(url.protocol);         // "https:"
console.log(url.hostname);         // "example.com"
console.log(url.port);             // "8443"
console.log(url.pathname);         // "/docs/guide"
console.log(url.searchParams.get("tab"));   // "api"
console.log(url.hash);             // "#section"
console.log(url.origin);           // "https://example.com:8443"

// The search parameters are a live API.
url.searchParams.set("page", "3");
console.log(url.search);           // "?tab=api&page=3"

The searchParams property is the part that saves the most time. It is a full URLSearchParams object, so you can read a single parameter with the get method, check for one with has, iterate over them with the entries method, and add or remove them without touching the query string by hand. Because it is a live view, changing it updates the URL object straight away.

Two details about encoding. Values in a query string are percent encoded, so a value with a space or an ampersand in it comes back decoded when you use get, and the get method decodes it for you. And the whole thing is normalised for you, so a URL with a missing scheme or a doubled slash is tidied up into its canonical form.

The other reason to use the API rather than string splitting is that it handles the awkward cases correctly. IPv6 hosts, ports with a default value, and paths with encoded characters all get parsed properly, where a regular expression would need a special case for each of them.

You construct a URL from a base and a path, then change the pieces you need. The constructor takes two arguments when the first one is relative.

// Build a URL from parts.
const api = new URL("/v1/users", "https://api.example.com");
console.log(api.toString());   // "https://api.example.com/v1/users"

api.searchParams.append("include", "roles");
api.pathname = "/v2/users";
console.log(api.toString());   // "https://api.example.com/v2/users?include=roles"

// Relative URLs need a base.
const relative = new URL("../other", "https://example.com/docs/guide");
console.log(relative.pathname);   // "/other"

// URLSearchParams on its own.
const params = new URLSearchParams({ tab: "api", page: "2" });
console.log(params.get("tab"));   // "api"
console.log(params.toString());   // "tab=api&page=2"

The two-argument form is the one to reach for. It resolves a relative reference against a base, exactly like a link in the page would, so a relative path that goes up and out of the current directory is handled the way you expect rather than producing a broken path.

Modifying a URL in place is straightforward. Assign to pathname, hash, hostname or port and the object updates. The search string is the exception, because it is better to use the searchParams object, which handles the encoding and the question mark for you.

There is a subtlety with the searchParams and the toString method. The toString method percent encodes the values, so a value containing a space becomes a plus sign or a percent sequence. If you read a parameter back with the get method, you get the decoded value, so the round trip is safe. What is not safe is building a query string by hand and then parsing it, because the encoding rules are easy to get wrong.

Three come up repeatedly, and all of them involve taking a URL from an untrusted source and acting on it.

Open redirects. If your application takes a target URL from a query parameter and sends the user there, an attacker can craft a link that passes your checks and then lands the user somewhere else. The fix is to allow only paths on your own origin, and to check the parsed origin rather than the string, because a value like a protocol-relative URL or one with an embedded newline can slip past a naive check.

Cross-site scripting through the URL. A URL whose scheme is the javascript one is not a normal URL, and setting it as the location of a link runs code. That is why you must check the protocol before navigating, and why a sanitiser that only looks for the word script is not enough.

Injection through the query string. Every parameter you read from a URL came from the user. If a parameter is used to build a database query, a file path or a shell command, it has to be validated or escaped. The URL API helps by decoding the value for you, which is exactly why it is easy to forget that the decoded value is the dangerous one.

Two more practical points. The username and password parts of a URL are a bad way to carry credentials, because they end up in logs and in the browser history. And when you read the hash of a URL, remember that it is not sent to the server, so it is a client-side only mechanism, and anything you keep there is visible to the user and to any script on the page.