How Axios Resolves Relative Paths with baseURL

When configuring the Axios HTTP client, setting a baseURL that includes path segments (such as /api/v1) affects how subsequent relative request URLs are constructed. Unlike standard browser URL resolution rules, Axios uses a dedicated joining mechanism that preserves sub-paths in the base URL regardless of whether the relative request path starts with a leading forward slash. This article explains how Axios resolves relative paths alongside a baseURL containing path segments and how it differs from standard web platform resolution.

The Axios Path Concatenation Mechanism

Axios uses an internal helper function called buildFullPath to combine the baseURL and the requested url.

When both baseURL and a relative path are provided, Axios performs the following steps:

  1. Checks if the requested url is an absolute URL. If it starts with a protocol scheme (e.g., http://, https://) or a protocol-relative slash (//), Axios ignores the baseURL entirely and uses the requested URL as-is.
  2. If the requested url is relative, Axios strips any trailing slash from the baseURL and any leading slash from the requested url.
  3. It joins the cleaned baseURL and relative url using a single forward slash (/).

Axios Resolution vs. Standard WHATWG URL Resolution

In the standard WHATWG URL API and browser navigation, a leading forward slash in a relative path indicates an absolute path relative to the domain root. For example, new URL('/users', 'https://example.com/api/v1') resolves to https://example.com/users, stripping the /api/v1 segment.

Axios intentionally deviates from this standard to provide predictable API client behavior:

Base URL Request URL Axios Result WHATWG URL Result
https://example.com/api/v1 /users https://example.com/api/v1/users https://example.com/users
https://example.com/api/v1/ users https://example.com/api/v1/users https://example.com/api/v1/users
https://example.com/api/v1/ /users https://example.com/api/v1/users https://example.com/users
https://example.com/api/v1 https://other.com/data https://other.com/data https://other.com/data

Resolution Behavior Scenarios

1. Relative Path with a Leading Slash

const client = axios.create({
  baseURL: 'https://example.com/api/v1'
});

// Request to: https://example.com/api/v1/posts
client.get('/posts');

Axios strips the leading / from /posts and appends it to the base path, retaining /api/v1.

2. Relative Path without a Leading Slash

const client = axios.create({
  baseURL: 'https://example.com/api/v1'
});

// Request to: https://example.com/api/v1/posts
client.get('posts');

The result is identical to the leading-slash scenario. Axios ensures both patterns produce the same endpoint.

3. Trailing Slashes on Base URL

const client = axios.create({
  baseURL: 'https://example.com/api/v1/'
});

// Request to: https://example.com/api/v1/posts
client.get('/posts');

Axios normalizes the boundary, ensuring no double slashes (//) appear between the base path and the relative path.

4. Absolute URLs

const client = axios.create({
  baseURL: 'https://example.com/api/v1'
});

// Request to: https://external-service.com/health
client.get('https://external-service.com/health');

When an absolute URL is passed, Axios bypasses the baseURL completely.

Key Takeaways