Skip to content
Go: Resolve relative URLs against the intended base path

Go: Resolve relative URLs against the intended base path

November 19, 2026

A missing trailing slash can send a relative API reference to the wrong path. URL.ResolveReference applies URI resolution rules: a relative path replaces the last base-path segment unless the base ends with a slash. Test the base and reference together before making a request.

Set up

Tested on Linux amd64 with Go 1.26.10. Use Bash with Go on your PATH, a text editor, and the mktemp, rm, and rmdir utilities. The example uses only the standard library. Keep the same terminal through cleanup, and stop if setup fails before saving the source.

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save as go-url-resolve-reference-base-path.go:

package main

import (
	"fmt"
	"net/url"
)

func parse(raw string) *url.URL {
	u, err := url.Parse(raw)
	if err != nil {
		panic(err)
	}
	return u
}

func main() {
	child := parse("items?limit=2")
	for _, raw := range []string{"https://example.com/api/v1", "https://example.com/api/v1/"} {
		base := parse(raw)
		fmt.Printf("base=%s child=%s\n", base, base.ResolveReference(child))
	}
	base := parse("https://example.com/api/v1/")
	for _, raw := range []string{"/health", "../status", "https://other.example/report"} {
		fmt.Printf("reference=%q result=%s\n", raw, base.ResolveReference(parse(raw)))
	}
	fmt.Println("base unchanged:", base)
}

Run:

go run go-url-resolve-reference-base-path.go

Observed output:

base=https://example.com/api/v1 child=https://example.com/api/items?limit=2
base=https://example.com/api/v1/ child=https://example.com/api/v1/items?limit=2
reference="/health" result=https://example.com/health
reference="../status" result=https://example.com/api/status
reference="https://other.example/report" result=https://other.example/report
base unchanged: https://example.com/api/v1/

Read the result

With the first base, the child path replaces the final segment. The second base ends with a slash, so the child path follows that segment. The query in the child reference stays attached to the resolved result.

The remaining references exercise different rules. A leading slash starts at the host root, the parent segment moves up one path level, and an absolute URL replaces the base entirely. Resolution returns a new URL value; the printed base remains unchanged.

Apply it carefully

Choose a directory-style base only when that is the intended API contract. A trailing slash is part of URL semantics, not proof that a server has a directory or endpoint at that path. This program parses and resolves strings locally; it makes no network requests and does not check endpoint existence.

Resolution does not constrain a reference to the base host or path. If references come from outside your application, validate the resolved destination before using it, including the scheme, host and allowed path. Redirects need their own policy. For adding query values to an existing address, use the query APIs rather than treating the values as relative paths.

See URL.ResolveReference and the URI resolution algorithm.

Clean up

Remove the saved source and the empty scratch directory. Go manages its build cache separately. If the directory is not empty, inspect its contents before removing anything else.

rm -- go-url-resolve-reference-base-path.go
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on