Retrofit – Getting Started and Creating an Android Client

Retrofit – Getting Started and Creating an Android Client

Hi guys! This is the first tutorial in an extensive series on Retrofit. The series dives through all aspects of Retrofit and prepares you for many potential use cases. You’ll get to know Retrofit’s range of functions and extensibility.

Within this first tutorial we’re going through the basics of Retrofit and create an Android client for HTTP requests against the GitHub API.

What is Retrofit?

The official page describes Retrofit as

A type-safe REST client for Android and Java.

You’ll use annotations to describe HTTP requests, URL parameter replacement and query parameter support is integrated by default. Additionally, it provides functionality for custom headers, multipart request body, file uploads and downloads, mocking responses and much more. In later tutorials we’ll look at all of these in more details.

Prepare Your Android Project

Let’s get our hands dirty and back to the keyboard. If you already created your Android project, just go ahead and start from the next section. Otherwise, create a new project in our favorite IDE, Android Studio. I prefer Android Studio with Gradle as the build system, but you surely can use your IDE of choice or Maven as well.

Define Dependencies: Gradle

At first, set Retrofit as a dependency for your project. Define Retrofit and its dependencies in your build.gradle. When running the command to build your code, the build system will download and provide the library for your project.

Retrofit 2

I recommend Retrofit 2 as it leverages OkHttp as the networking layer by default and is built on top of it. You don’t need to explicitly define OkHttp as a dependency for your project, unless you have a specific version requirement.

However, Retrofit 2 requires a dependency for the automatic conversion of request and response payloads. Use the following dependencies if you’re using Retrofit in version 2 and want to map JSON payloads with GSON:

Android’s Network Permission

Retrofit performs HTTP requests against an API running on a server somewhere in the Internet. Executing those requests from an Android application requires the Internet permission to open network sockets. You need to define the permission within the AndroidManifest.xml file. If you didn’t set the Internet permission yet, please add the following line within your AndroidManifest.xml definition:

How to Describe API Endpoints

Before you can start with your first requests, you need to describe the API endpoints you want to interact with. In this tutorial we’ll just describe a simple GitHub endpoint. We’ll go into more detail on API endpoint description in a later tutorial.

First, you have to create an interface and define required methods.

GitHub Client

The following code defines the GitHubClient and a method reposForUser to request the list of repositories for a given user. The @GET annotation declares that this request uses the HTTP GET method. The code snippet also illustrates the usage of Retrofit’s path parameter replacement functionality. In the defined method the {user} path will be replaced with the given variable values when calling the reposForUser method.

Retrofit 2

There is a defined class GitHubRepo. This class comprises required class properties to map the response data.

With regard to the previously mentioned JSON mapping: the GitHubClient interface defines a method named reposForUser with return type List<GitHubRepo>. Retrofit makes sure the server response gets mapped correctly (in case the response matches the given class).

Retrofit REST Client

After describing the API interface and the object model, it’s time to prepare an actual request. Retrofit’s basis for all requests is the Retrofit (2.0+) class. You create and configure it with a fluent API. To that end, you can use the builder to set some general options for all requests, i.e. the base URL or the converter. We’ll go into more detail for all of the available options in a later tutorial.

Once you’ve created an adapter, you’re able to create a client. You’ll use the client to execute the actual requests.

Retrofit 2

In our example, GitHub’s API base URL is In the code snippets above we just went with the minimum options. There are a lot more options for fine-tuned control over your requests. But it’s sufficient for the purpose of making our first request!

JSON Mapping

In most cases requests to a server, and the responses from the server, are not Java objects. They’re mapped to some language neutral format like JSON. Since GitHub’s API uses JSON, we need to prepare Retrofit for it.

Retrofit 1.9 ships with Google’s Gson (which parses JSON to and from Java objects) by default. All you need to do is define the class of your response object and the response will be mapped automatically.

When using Retrofit 2, you need to add a converter explicitly to the Retrofit object.  Above, we have added the following line in our build.gradle file to import the Gson converter.

If you followed our tutorial from the beginning, you’ve already done this!

Retrofit in Use

After doing a ton of prep work, it’s time to reap the benefits and finally make your request. The good news: it’s only going to be a few lines!

The first line of creating a client object should already be familiar. The way of actually executing the request depends on the Retrofit version.

Retrofit 2

In Retrofit 2, you also use your client object. However, here you don’t pass your callback as the last parameter. You use the client to get a call object. Once you’ve invoked .enqueue on the created call object the request will be made by Retrofit. There is also an option to do a synchronous request, but we’ll look at those later.

In either case, you should be able to make your very first request with Retrofit. If everything went well, Retrofit will return you a handy List<GitHubRepo>, which you can further use to display the data in your app.

Initially, Retrofit looks pretty complex. We promise, it’s very clean and pays off if you’re working on a larger project. If you spend a little more time reading a few more tutorials, you’ll soon also love Retrofit.

What Comes Next?

In this tutorial you’ve learned the basics of Retrofit. In multiple sections we’ve only given you the code without much explanations. We highly recommend to read up on those parts in more detail. You should start by reading how to describe API endpoints with Retrofit, which will be available soon.

If you’ve feedback or a question, let me know in the comments.

Happy Coding!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.