2. Tutorials
  3. Retrofit 2 — How to Change API Base Url at Runtime

Retrofit 2 — How to Change API Base Url at Runtime

In this tutorial we'll show you a very handy tool, which can make your debugging life so much easier. If you're an Android app developer and you've to deal with multiple versions of an API (for example develop, staging and production) you're probably tired of building three (or more) versions of the app, if you quickly want to see if your app works against all server deployments.

In the next few minutes, you'll learn how you can change the API base url at runtime! This means, you can check with one compilation and installation how your app behaves with all API versions.

In the last few months, we've published a variety of Retrofit tutorials:

Retrofit Series Overview

  1. Synchronous and Asynchronous Requests
  2. Send Objects in Request Body
  3. Add Custom Request Header
  4. Manage Request Headers in OkHttp Interceptor
  5. Dynamic Request Headers with @HeaderMap
  6. Multiple Query Parameters of Same Name
  7. Optional Query Parameters
  8. Send Data Form-Urlencoded
  9. Send Data Form-Urlencoded Using FieldMap
  10. How to Add Query Parameters to Every Request
  11. Add Multiple Query Parameter With QueryMap
  12. How to Use Dynamic Urls for Requests
  13. Constant, Default and Logic Values for POST and PUT Requests
  14. Cancel Requests
  15. Reuse and Analyze Requests
  16. Optional Path Parameters
  17. How to Send Plain Text Request Body
  18. Customize Network Timeouts
  19. How to Trust Unsafe SSL certificates (Self-signed, Expired)
  20. Dynamic Endpoint-Dependent Interceptor Actions
  21. How to Update Objects on the Server (PUT vs. PATCH)
  22. How to Delete Objects on the Server
  1. Ignore Response Payload with Call<Void>
  2. Receive Plain-String Responses
  3. Crawl HTML Responses with jspoon (Wikipedia Example)
  4. Loading Data into RecyclerView and CardView
  1. Introduction to (Multiple) Converters
  2. Adding & Customizing the Gson Converter
  3. Implementing Custom Converters
  4. How to Integrate XML Converter
  5. Access Mapped Objects and Raw Response Payload
  6. Supporting JSON and XML Responses Concurrently
  7. Handling of Empty Server Responses with Custom Converter
  8. Send JSON Requests and Receive XML Responses (or vice versa)
  9. Unwrapping Envelope Responses with Custom Converter
  10. Wrapping Requests in Envelope with Custom Converter
  11. Define a Custom Response Converter
  1. Simple Error Handling
  2. Error Handling for Synchronous Requests
  3. Catch Server Errors Globally with Response Interceptor
  4. How to Detect Network and Conversion Errors in onFailure
  1. Log Requests and Responses
  2. Enable Logging for Development Builds Only
  3. Log Network Traffic with Stetho and Chrome Developer Tools
  4. Using the Log Level to Debug Requests
  5. Analyze Network Traffic with Android Studio Profiler
  6. Debug and Compare Requests with RequestBin
  1. Introduction to Call Adapters
  2. Custom Call Adapter to Separate OnResponse Callback
  3. How to Integrate RxJava 1.x Call Adapter
  4. How to Integrate RxJava 2.x Call Adapter
  5. How to Integrate Guava Call Adapter
  6. Custom Call Adapter to Separate Network and Gson Errors
  1. Pagination Using Query Parameter
  2. Pagination Using Link Header and Dynamic Urls (Like GitHub)
  3. Pagination Using Range Header Fields (Like Heroku)
  1. How to Upload Files to Server
  2. How to Upload Multiple Files to Server
  3. How to Upload a Dynamic Amount of Files to Server
  4. Upload Files with Progress
  5. Passing Multiple Parts Along a File with @PartMap
  6. How to Download Files from Server
  7. Download Files with Progress Updates
  8. How to Upload Files to Server
  1. Basic Authentication on Android
  2. Token Authentication on Android
  3. OAuth on Android
  4. Hawk Authentication on Android
  5. How to Refresh an Access Token
  1. Activate Response Caching (Etag, Last-Modified)
  2. Check Response Origin (Network, Cache, or Both)
  3. Force Server Cache Support with Response Interceptor
  4. Support App Offline Mode by Accessing Response Caches
  5. Analyze Cache Files
  1. Basics of Mocking Server Responses
  2. Customizing Network Behavior of Mocked Server Responses
  3. Mock APIs with JsonServer
  1. Callbacks
  2. Annotations
  3. Fluent Interface with Builders

The Core: ServiceGenerator

Long time readers will know most of our Retrofit tutorials utilize our ServiceGenerator class from the creating a sustainable android client tutorial. Since we'll mainly work in the ServiceGenerator code, make sure you're familiar with this class.

In the current version the ServiceGenerator works with multiple static fields and a String constant API_BASE_URL, which holds the API base url:

public class ServiceGenerator {  
    public static final String API_BASE_URL = "http://futurestud.io/api";
    private static Retrofit retrofit;

    private static Retrofit.Builder builder =
            new Retrofit.Builder()
                    .addConverterFactory(GsonConverterFactory.create())
                    .baseUrl(API_BASE_URL);

    private static OkHttpClient.Builder httpClient =
            new OkHttpClient.Builder();

    // No need to instantiate this class.
    private ServiceGenerator() {

    }

    public static <S> S createService(Class<S> serviceClass, AccessToken token) {
        String authToken = token.getTokenType().concat(token.getAccessToken());
        return createService(serviceClass, authToken);
    }

    // more methods
    // ...
}

Adjusting the ServiceGenerator

With this setup you don't have a chance to change the API_BASE_URL constant at runtime. You've change it in the source code, compile a new .apk and test it again. Since this is very inconvenient if you're working with multiple API deployments, we'll make minor changes to the ServiceGenerator class:

public class ServiceGenerator {  
    public static String apiBaseUrl = "http://futurestud.io/api";
    private static Retrofit retrofit;

    private static Retrofit.Builder builder =
            new Retrofit.Builder()
                    .addConverterFactory(GsonConverterFactory.create())
                    .baseUrl(apiBaseUrl);

    private static OkHttpClient.Builder httpClient =
            new OkHttpClient.Builder();

    // No need to instantiate this class.
    private ServiceGenerator() {
    }

    public static void changeApiBaseUrl(String newApiBaseUrl) {
        apiBaseUrl = newApiBaseUrl;

        builder = new Retrofit.Builder()
                        .addConverterFactory(GsonConverterFactory.create())
                        .baseUrl(apiBaseUrl);
    }

    public static <S> S createService(Class<S> serviceClass, AccessToken token) {
        String authToken = token.getTokenType().concat(token.getAccessToken());
        return createService(serviceClass, authToken);
    }

    // more methods
    // ...
}

Let's examine our changes. We've renamed the constant API_BASE_URL to a non-final field apiBaseUrl. We also added a new static method changeApiBaseUrl(String newApiBaseUrl), which will change that particlar apiBaseUrl variable. It also creates a new version of the Retrofit.Builder instance builder. This is important because we're re-using the builder for requests. If we don't create a new instance all requests still would have gone against the original apiBaseUrl value.

Example Usage

We've made the necessary changes to the ServiceGenerator. Let's move on to actually utilize our new functioanlity:

public class DynamicBaseUrlActivity extends AppCompatActivity {

    public static final String TAG = "CallInstances";
    private Callback<ResponseBody> downloadCallback;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_file_upload);

        downloadCallback = new Callback<ResponseBody>() {
            @Override
            public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {
                Log.d(TAG, "server contacted at: " + call.request().url());
            }

            @Override
            public void onFailure(Call<ResponseBody> call, Throwable t) {
                Log.d(TAG, "call failed against the url: " + call.request().url());
            }
        };

        // first request
        FileDownloadService downloadService = ServiceGenerator.create(FileDownloadService.class);
        Call<ResponseBody> originalCall = downloadService.downloadFileWithFixedUrl();
        originalCall.enqueue(downloadCallback);

        // change base url
        ServiceGenerator.changeApiBaseUrl("http://development.futurestud.io/api");

        // new request against new base url
        FileDownloadService newDownloadService = ServiceGenerator.create(FileDownloadService.class);
        Call<ResponseBody> newCall = newDownloadService.downloadFileWithFixedUrl();
        newCall.enqueue(downloadCallback);
    }
}

In this activity we're showing you two requests to download a file from the server. If you're interested in the details on how to download files with Retrofit, head over to the relevant tutorial. After the first request is executed, we change the base url to our development environment with the new ServiceGenerator.changeApiBaseUrl() method. Lastly, we'll make the same download request again. When we start the app, we're getting the following logs:

D/CallInstances: server contacted at: http://futurestud.io/resource/example.zip  
D/CallInstances: server contacted at: http://development.futurestud.io/resource/example.zip

This is exactly as we wanted Retrofit to behave. The first request still goes against the production server. The second request, after changing the base url, goes against our development server. Awesome!

When To Change the Base Url at Runtime

The demo code above simplifies things a little. We usually implement a button in the debug version of the app, where the tester can select the wished server environment. Thus, depending on your situation, you probably have to write a bit more code to decide when and to which base url Retrofit should change to.

Also, we only recommend doing this for debugging purposes. We don't think this is a good way of making your app work with various servers at the same time. If your app needs to deal with more than one API, look for a different version. The dynamic url tutorial might be a good start.

Lastly, please test if you can simply switch environments with your app. For example, if you store user and authentication information on the server side, switching the environment might cause problems. Your production database most likely does not contain the same users as your development database, correct? In our apps, we delete all relevant user data and force a new, fresh login after the tester changed the environment via a new base url.

Summary

In this tutorial, you've learned how to change the API base url at runtime. This can be incredibly useful if you're dealing with multiple API deployments. We've shown you the necessary enhancement to the ServiceGenerator class and how to make the necessary requests. You also have to be aware of the possible consequences when switching API deployments during runtime. Nevertheless, if you spent the hour to implement this for your app, you'll save days of compiling time!

If you think is useful or if you've any questions, let us know in the comments!

Norman Peitek

android & node.js dev

https://twitter.com/peitek

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous