Retrofit for Java: Type-safe HTTP Client for Android and Java

1. What It Is and Why You Need It

Retrofit is a powerful and elegant library for Java (and Android) that turns an HTTP API into a Java interface. Instead of manually writing boilerplate code for creating HTTP requests, handling responses, and parsing JSON, Retrofit does all this work for you. It automatically serializes your Java objects into JSON (or another format) for sending to the server and deserializes server responses back into Java objects. This makes the code clean, readable, and easy to maintain.

Why do you need it? Imagine you need to write an application that communicates with a REST API (e.g., GitHub API, OpenWeatherMap, or your own server). Without Retrofit, you would have to use low-level classes like HttpURLConnection or HttpClient, manually form URLs, set headers, handle error codes, and parse JSON. This is not only tedious but also error-prone. Retrofit solves these problems by providing a declarative way to describe an API. You simply create an interface with methods, annotate them (e.g., @GET, @POST), and Retrofit automatically generates the implementation of that interface.

Retrofit is the de facto standard for working with HTTP in the Android and Java world. It integrates tightly with OkHttp (for efficient networking) and Gson/Moshi (for JSON serialization). The library supports synchronous and asynchronous requests, file uploads, authentication, caching, and many other features. Thanks to its simplicity and flexibility, Retrofit is used in thousands of applications and services worldwide.

2. Installation

Retrofit is distributed via Maven Central. To use it in your Java project (e.g., with Maven or Gradle), add the appropriate dependencies. Note that you will also need a converter for serialization (most often Gson or Moshi) and OkHttp itself (which Retrofit uses under the hood).

Maven (pom.xml)

<!-- Retrofit -->\n<dependency>\n    <groupId>com.squareup.retrofit2</groupId>\n    <artifactId>retrofit</artifactId>\n    <version>2.9.0</version>\n</dependency>\n\n<!-- Gson Converter (for JSON) -->\n<dependency>\n    <groupId>com.squareup.retrofit2</groupId>\n    <artifactId>converter-gson</artifactId>\n    <version>2.9.0</version>\n</dependency>\n\n<!-- OkHttp (usually pulled automatically, but you can explicitly specify a version) -->\n<dependency>\n    <groupId>com.squareup.okhttp3</groupId>\n    <artifactId>okhttp</artifactId>\n    <version>4.12.0</version>\n</dependency>

Gradle (build.gradle)

dependencies {\n    implementation 'com.squareup.retrofit2:retrofit:2.9.0'\n    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'\n    implementation 'com.squareup.okhttp3:okhttp:4.12.0'\n}

Important: Versions may become outdated. Always check the latest versions on the official website or in the Maven Central repository. If you use a different converter (e.g., Moshi or Jackson), replace converter-gson with the corresponding artifact (converter-moshi, converter-jackson).

3. Quick Start — Minimal Working Example

Let's write a simple example that fetches a list of users from the JSONPlaceholder server (a test REST API).

Step 1: Create a data model (POJO)

// User.java\npublic class User {\n    private int id;\n    private String name;\n    private String username;\n    private String email;\n\n    // Getters (required for Gson)\n    public int getId() { return id;