Resolve API endpoints
Create absolute endpoints from service roots and relative resource paths.
Node.js · Class
URL
The WHATWG URL class parses absolute URLs and resolves relative references against a base URL. It exposes structured URL components and serializes them back into standard URL strings.
- Since
- v7.0.0, v6.13.0
How it works
The WHATWG URL class parses an absolute URL or resolves a relative URL against a base URL into structured components. Its properties expose parts such as the protocol, hostname, pathname, and query parameters, while serialization methods produce the resulting URL string.
Syntax
new URL(input[, base])Parameters
| Name | Type | Description |
|---|---|---|
input | string | The URL string or relative reference to parse. |
base | string | URL | The absolute base URL used when input is relative. |
Returns
A URL object containing properties for the URL's components.
Key points
- The class follows the browser-oriented WHATWG URL standard, making URL handling consistent across Node.js and web environments.
- Parsing separates one URL string into independently accessible components instead of requiring manual string manipulation.
- The constructor returns a URL object whose properties expose the parsed parts of the address.
- URL can be used directly as a global in Node.js without importing the node:url module.
- Calling toString produces the serialized representation of the URL object.
Common mistakes
- Node.js exposes the WHATWG URL class globally, so importing it is optional; importing from node:url can make the dependency explicit.
Example: Resolve and inspect a URL
import { URL } from 'node:url';
const endpoint = new URL('/users', 'https://api.example.com/v1/');
endpoint.searchParams.set('active', 'true');
console.log(endpoint.href);
console.log(endpoint.hostname);Constructs an absolute URL from a relative path and base, adds a query parameter, and reads parsed components.
When to use it
Inspect and edit URL components
Read or modify host, path, protocol, and query components without manual string parsing.
Standardize URL handling
Build browser-compatible URLs for HTTP requests, redirects, and routing.
Interview questions
QWhat is Node.js's URL class?
The WHATWG URL class is a browser-compatible URL implementation available through Node.js. It turns a URL string into an object whose properties represent its meaningful components.
Follow-up: How do you resolve a relative URL? Construct URL with the relative reference as the first argument and an absolute base URL as the second.
QHow is a URL constructed from a relative path?
Use new URL(input, base) when the input may be relative; the base supplies the missing context. For an already absolute URL, new URL(input) is sufficient.
Follow-up: What happens if a relative input is supplied without a base? Construction cannot resolve it as an absolute URL and throws an error.
QHow do you inspect and serialize a parsed URL?
The URL object provides structured components, and toString() serializes the object back into a URL string. The class follows the WHATWG URL Standard, aligning its behavior with web browsers.
Follow-up: How should legacy URL parsing be treated? It remains available for compatibility, but the WHATWG API is the modern choice for new code.
Related
URLSearchParamsurl.parse()url.format()url.resolve()