Introduction

When URL parts come from variables, manual string concatenation becomes fragile very quickly. In Android, Uri.Builder exists to build URIs safely by separating scheme, host, path segments, and query parameters so encoding mistakes do not leak into your app.

Why String Concatenation Fails So Easily

Code like this looks simple:

val url = "https://api.example.com/search?q=" + query + "&page=" + page

The problem is that real input is messy:

• queries contain spaces
• values may contain & or ?
• optional parameters require awkward delimiter logic
• path segments can accidentally create double slashes

Once variable data enters the picture, building URLs by hand is usually the wrong abstraction.

Uri.Builder Solves the Structure Problem

Uri.Builder lets you express the URI as separate parts:

1import android.net.Uri
2
3fun main() {
4    val userId = 42
5    val search = "red shoes"
6
7    val uri = Uri.Builder()
8        .scheme("https")
9        .authority("api.example.com")
10        .appendPath("users")
11        .appendPath(userId.toString())
12        .appendQueryParameter("q", search)
13        .appendQueryParameter("limit", "10")
14        .build()
15
16    println(uri.toString())
17}

This produces:

https://api.example.com/users/42?q=red%20shoes&limit=10

The space in "red shoes" is encoded automatically. That is exactly the kind of bug Uri.Builder prevents.

Path Segments and Query Parameters Are Different

One reason builders are so useful is that they distinguish between path and query semantics.

Use:

• 'appendPath(...) for hierarchical path segments'
• 'appendQueryParameter(...) for query string values'

That distinction matters because slashes, ampersands, and other characters are treated differently in those two parts of a URI. Manual string assembly makes it easy to blur the line.

Building from an Existing Base URI

If your app already has a base endpoint, parse it once and extend it:

1import android.net.Uri
2
3val base = Uri.parse("https://api.example.com/v1")
4
5val full = base.buildUpon()
6    .appendPath("products")
7    .appendQueryParameter("sort", "price")
8    .appendQueryParameter("direction", "asc")
9    .build()
10
11println(full)

This is useful when the host comes from configuration but the path and query are request-specific.

Optional Parameters Become Much Cleaner

Builders also make conditional logic manageable. You can append only the parameters that actually exist:

1import android.net.Uri
2
3fun buildSearchUri(query: String, category: String?): Uri {
4    val builder = Uri.Builder()
5        .scheme("https")
6        .authority("api.example.com")
7        .appendPath("search")
8        .appendQueryParameter("q", query)
9
10    if (category != null) {
11        builder.appendQueryParameter("category", category)
12    }
13
14    return builder.build()
15}

Notice how there is no manual decision about whether the next separator should be ? or &. The builder handles that.

Uri.Builder Versus Networking Library Builders

If you are building links, deep links, Android resource URIs, or simple app-generated web URLs, Uri.Builder is a strong default.

If you are inside an HTTP client stack such as OkHttp or Retrofit, the networking library may offer an even better URL abstraction. For example, OkHttp has HttpUrl.Builder, which is tailored to HTTP semantics.

The practical rule is:

• use Uri.Builder for Android URI composition in general
• use your HTTP client's builder if the networking layer already provides one

Either choice is better than string concatenation when variables are involved.

A Note on Readability

Some developers hesitate because the builder syntax is longer than one string interpolation expression. That is true for trivial cases. But as soon as variables, optional filters, or encoding-sensitive values appear, the builder version is usually shorter to debug and much safer to maintain.

Common Pitfalls

The biggest pitfall is using string concatenation for query parameters that can contain spaces or special characters. That is the path to subtle bugs.

Another pitfall is using appendPath() for data that really belongs in the query string. Path and query values are not interchangeable.

A third pitfall is mixing Android URI construction with a networking library that already has its own safer HTTP URL builder. Pick the abstraction that matches the layer you are working in.

Finally, do not assume user input is already safe to embed in a URL. Let the builder handle encoding instead of trying to escape values manually.

Summary

• 'Uri.Builder is usually better than manual string concatenation when URLs contain variables'
• It separates scheme, authority, path, and query logic cleanly
• 'appendQueryParameter(...) handles encoding automatically'
• Optional parameters are easier to manage with a builder than with raw string assembly
• If your HTTP client already provides a URL builder, prefer that inside the networking layer