Easy HTTP Requests with Retrofit

A declarative, type-safe REST client.

Square Engineering
May 13, 2013 · 2 min read

Written by Jake Wharton.

There are few fundamentals to application development. One that is almost always guaranteed is making HTTP requests and reading their responses. Retrofit is an open source library from Square which simplifies HTTP communication by turning remote APIs into declarative, type-safe interfaces.

Methods declared on an interface represent a single remote API endpoint. Annotations describe how the method maps to an HTTP request.

To demonstrate how Retrofit works we will use it to list the top contributors on OkHttp’s GitHub project.

Declaring API

GitHub’s well-documented API provides a call to list all contributors on a repository. Here’s what an interface containing that call looks like:

public interface GitHubService {
@GET("/repos/{owner}/{repo}/contributors")
List<Contributor> contributors(
@Path("owner") String owner,
@Path("repo") String repo
);
}

Let’s break down what the above interface contains:

  • @GET(“/repos/{owner}/{repo}/contributors”) — This is both the HTTP request method (“GET”) and the relative URL to fetch. The {owner} and {repo} strings are replacement blocks.
  • @Path(“owner”) and @Path(“repo”) define method arguments that will be used for replacing sections in the URL.
  • List<Contributor> — The type of the response body.

For this to work we will need a small Contributor type.

public class Contributor {
public String login; // GitHub username.
public int contributions; // Commit count.
}

Using RestAdapter

RestAdapter is the class which transforms an API interface into an object which actually makes
network requests.

In order to use our GitHubService we need to create a RestAdapter and then use it to create a real
instance of the interface.

RestAdapter restAdapter = new RestAdapter.Builder()
.setServer("https://api.github.com") // The base API endpoint.
.build();
GitHubService github = restAdapter.create(GitHubService.class);

To list contributors, we call our method with the appropriate data.

List<Contributor> contributors = github.contributors("square", "okhttp");
for (Contributor contributor : contributors) {
log(contributor.login + " - " + contributor.contributions);
}

Not only have we hidden the complexities of HTTP away from our implementation code, we’ve also hidden the URL structure and requirements of the GitHub API into testable Java objects.

Retrofit 1.0

More information about configuring and using Retrofit as well as downloads can be found on its website.

Fun fact: Retrofit is actually Square’s oldest open source project! The first commitwas made by Bob Lee on September 6th, 2010!

This post is part of Square’s “Seven Days of Open Source” series.


Square Corner Blog

Buying and selling sound like simple things - and they…

Square Engineering

Written by

The official account for @Square Engineering.

Square Corner Blog

Buying and selling sound like simple things - and they should be. Somewhere along the way, they got complicated. At Square, we're working hard to make commerce easy for everyone.

Square Engineering

Written by

The official account for @Square Engineering.

Square Corner Blog

Buying and selling sound like simple things - and they should be. Somewhere along the way, they got complicated. At Square, we're working hard to make commerce easy for everyone.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store