Retrofit 2 — How to Use Dynamic Urls for Requests

Retrofit 2 finally comes with an additional annotation for dynamic urls. What was a hackaround in Retrofit 1 is now just a single @Url annotation for the endpoint declaration.

This post will show you how to make use of dynamic endpoint urls for individual requests.

Retrofit Series Overview

  1. Callbacks (Coming soon)
  2. Annotations (Coming soon)
  3. Fluent Interface with Builders (Coming soon)

Use-Case Scenarios

There might not directly come a use case to your mind that requires the definition of the endpoint url on the fly. We can give you two examples to illustrate real world scenarios.

  1. Profile Pictures: if your app allows users to upload their personalized profile picture, you might store them on different locations like your own server, Amazon S3 or maybe you also allow the linking of Gravatar.
  2. File Downloads: Files can be stored at varios locations and you want/need to be flexible to download them from any resource path.

Even though your Android app didn’t have any of the proposed functionality, you’re now in the appropriate mindset to imagine examples where dynamic urls are a good fit to make use of.

How to Use Dynamic Urls

Actually, it only requires you to add a single String parameter annotated with @Url in your endpoint definition. Short code says more than thousand words :)

public interface UserService {  
    public Call<ResponseBody> profilePicture(@Url String url);

As you can see, you’ll leave the @GET annotation without the endpoint url and add the @Url to the method itself.

How Urls Resolve Against Your Base Url

That’s another interesting part and needs attention: how will the dynamic url be resolved against the defined base url? Retrofit 2 uses OkHttp’s HttpUrl and resolves each endpoint url like a link on any website (<a href="">…</a>).

Let’s touch some scenarios and at first look at a url that points to a profile picture stored on Amazon S3. We’ll have a base url defined and the actual call of the profilePicture method uses a completely different one.

Retrofit retrofit = Retrofit.Builder()  

UserService service = retrofit.create(UserService.class);  

// request url results in:

Because you set a completely different host including a scheme ( vs. https://your.api.url), the HttpUrl from OkHttp will resolve it to the dynamic one.

Another example: this time we point the dynamic url for our profile picture to the same server as we’ve already defined as the base url.

Retrofit retrofit = Retrofit.Builder()  

UserService service = retrofit.create(UserService.class);  

// request url results in:
// https://your.api.url/profile-picture/path

This time, the final request url gets resolved to a concatenation of the base url and our dynamically defined endpoint url. HttpUrl will recognizes that we didn’t specify a scheme and host and therefore appends the endpoint url to the base url.

A third example: let’s assume the backend developers pushed an update to production that bumps the API’s base url to version 2.

Retrofit retrofit = Retrofit.Builder()  

UserService service = retrofit.create(UserService.class);  

// request url results in:
// https://your.api.url/profile-picture/path

The difference between the second and third examples is this: we’ve added v2/ to the base url and start the endpoint url with a leading /. Actually, this will result in the same final request url, because endpoint urls that start with a leading slash will be appended to only the base url’s host url. Everything that comes after the host url will be omitted when using leading slashes for endpoint urls. You can fix your problem by removing the leading / from your endpoint.


The thing that you need to watch out for is the correct “creation” of your request urls. The examples in this article show you common pitfalls and it’s easy to fall into that trap. Make sure you’re using either full urls including scheme, host and path or you have to put in extra work to catch some issues before using the url.

We’ve recognized that the url handling in Retrofit 2 definitely requires more attention and in tomorrow’s post you’ll learn how request urls will be revolved within different scenarios.

Explore the Library

Find interesting tutorials and solutions for your problems.