retrofit Documentation

File: README.md Copy Chapter

Retrofit

A type-safe HTTP client for Android and Java.

For more information please see the website.

Download Copy Chapter

Download the latest JAR or grab from Maven central at the coordinates com.squareup.retrofit2:retrofit:3.0.0.

Snapshots of the development version are available in Sonatype's snapshots repository.

Retrofit requires at minimum Java 8+ or Android API 21+.

R8 / ProGuard Copy Chapter

If you are using R8 the shrinking and obfuscation rules are included automatically.

ProGuard users must manually add the options from
retrofit2.pro.
You might also need rules for OkHttp which is a dependency of this library.

License

Copyright 2013 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

File: retrofit/java-test/README.md Copy Chapter

Retrofit Java Tests

These are in a separate module for two reasons:

• It ensures optional dependencies (Kotlin stuff) are completely absent.
• It uses the multi-release jar on the classpath rather than only the classes folder.

File: retrofit-adapters/java8/README.md Copy Chapter

Java 8 Adapter (Deprecated)

A call adapter Java 8's CompletableFuture.

This adapter is no longer needed. Support for CompletableFuture is built-in to Retrofit and now
works without configuration.

File: retrofit-adapters/guava/README.md Copy Chapter

Guava Adapter

An Adapter for adapting Guava ListenableFuture.

Usage Copy Chapter

Add GuavaCallAdapterFactory as a Call adapter when building your Retrofit instance:

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://example.com/")
    .addCallAdapterFactory(GuavaCallAdapterFactory.create())
    .build();

Your service methods can now use ListenableFuture as their return type.

interface MyService {
  @GET("/user")
  ListenableFuture getUser();
}

Download Copy Chapter

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>adapter-guava</artifactId>
  <version>latest.version</version>
</dependency>

or Gradle:

implementation 'com.squareup.retrofit2:adapter-guava:latest.version'

Snapshots of the development version are available in Sonatype's snapshots repository.

File: retrofit-adapters/rxjava/README.md Copy Chapter

RxJava Adapter

An Adapter for adapting RxJava 1.x types.

Available types:

• Observable<T>, Observable<Response<T>>, and Observable<Result<T>> where T is the body type.
• Single<T>, Single<Response<T>>, and Single<Result<T>> where T is the body type.
• Completable where response bodies are discarded.

Usage Copy Chapter

Add RxJavaCallAdapterFactory as a Call adapter when building your Retrofit instance:

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://example.com/")
    .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
    .build();

Your service methods can now use any of the above types as their return type.

interface MyService {
  @GET("/user")
  Observable getUser();
}

By default all reactive types execute their requests synchronously. There are multiple ways to
control the threading on which a request occurs:

• Call subscribeOn on the returned reactive type with a Scheduler of your choice.
• Use createAsync() when creating the factory which will use OkHttp's internal thread pool.
• Use createWithScheduler(Scheduler) to supply a default subscription Scheduler.

Download Copy Chapter

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>adapter-rxjava</artifactId>
  <version>latest.version</version>
</dependency>

or Gradle:

implementation 'com.squareup.retrofit2:adapter-rxjava:latest.version'

Snapshots of the development version are available in Sonatype's snapshots repository.

File: retrofit-adapters/rxjava2/README.md Copy Chapter

RxJava2 Adapter

An Adapter for adapting RxJava 2.x types.

Available types:

• Observable<T>, Observable<Response<T>>, and Observable<Result<T>> where T is the body type.
• Flowable<T>, Flowable<Response<T>> and Flowable<Result<T>> where T is the body type.
• Single<T>, Single<Response<T>>, and Single<Result<T>> where T is the body type.
• Maybe<T>, Maybe<Response<T>>, and Maybe<Result<T>> where T is the body type.
• Completable where response bodies are discarded.

Usage Copy Chapter

Add RxJava2CallAdapterFactory as a Call adapter when building your Retrofit instance:

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://example.com/")
    .addCallAdapterFactory(RxJava2CallAdapterFactory.create())
    .build();

Your service methods can now use any of the above types as their return type.

interface MyService {
  @GET("/user")
  Observable getUser();
}

By default all reactive types execute their requests synchronously. There are multiple ways to
control the threading on which a request occurs:

• Call subscribeOn on the returned reactive type with a Scheduler of your choice.
• Use createAsync() when creating the factory which will use OkHttp's internal thread pool.
• Use createWithScheduler(Scheduler) to supply a default subscription Scheduler.

Download Copy Chapter

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>adapter-rxjava2</artifactId>
  <version>latest.version</version>
</dependency>

or Gradle:

implementation 'com.squareup.retrofit2:adapter-rxjava2:latest.version'

Snapshots of the development version are available in Sonatype's snapshots repository.

File: retrofit-adapters/rxjava3/README.md Copy Chapter

RxJava3 Adapter

An Adapter for adapting RxJava 3.x types.

Available types:

• Observable<T>, Observable<Response<T>>, and Observable<Result<T>> where T is the body type.
• Flowable<T>, Flowable<Response<T>> and Flowable<Result<T>> where T is the body type.
• Single<T>, Single<Response<T>>, and Single<Result<T>> where T is the body type.
• Maybe<T>, Maybe<Response<T>>, and Maybe<Result<T>> where T is the body type.
• Completable where response bodies are discarded.

Usage Copy Chapter

Add RxJava3CallAdapterFactory as a Call adapter when building your Retrofit instance:

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://example.com/")
    .addCallAdapterFactory(RxJava3CallAdapterFactory.create())
    .build();

Your service methods can now use any of the above types as their return type.

interface MyService {
  @GET("/user")
  Observable getUser();
}

By default, create() will produce reactive types which execute their HTTP requests asynchronously
on a background thread. There are two other ways to control the threading on which a request
occurs:

• Use createSynchronous() and call subscribeOn on the returned reactive type with a Scheduler
  of your choice.
• Use createWithScheduler(Scheduler) to supply a default subscription Scheduler.

Download Copy Chapter

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>adapter-rxjava3</artifactId>
  <version>latest.version</version>
</dependency>

or Gradle:

implementation 'com.squareup.retrofit2:adapter-rxjava3:latest.version'

Snapshots of the development version are available in Sonatype's snapshots repository.

File: retrofit-adapters/scala/README.md Copy Chapter

Scala Adapter

An Adapter for adapting Scala Future.

Usage Copy Chapter

Add ScalaCallAdapterFactory as a Call adapter when building your Retrofit instance:

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://example.com/")
    .addCallAdapterFactory(ScalaCallAdapterFactory.create())
    .build();

Your service methods can now use Future as their return type.

interface MyService {
  @GET("/user")
  Future getUser();
}

Download Copy Chapter

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>adapter-scala</artifactId>
  <version>latest.version</version>
</dependency>

or Gradle:

implementation 'com.squareup.retrofit2:adapter-scala:latest.version'

Snapshots of the development version are available in Sonatype's snapshots repository.

File: retrofit-adapters/README.md Copy Chapter

Retrofit Adapters

Retrofit ships with a default adapter for executing Call instances. The child modules contained
herein are additional adapters for other popular execution mechanisms.

To use, supply an instance of your desired adapter when building your Retrofit instance.

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com")
    .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
    .build();

File: retrofit-converters/protobuf/README.md Copy Chapter

Google Protocol Buffer Converter

A Converter which uses Protocol Buffer binary serialization.

Download Copy Chapter

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>converter-protobuf</artifactId>
  <version>latest.version</version>
</dependency>

or Gradle:

implementation 'com.squareup.retrofit2:converter-protobuf:latest.version'

Snapshots of the development version are available in Sonatype's snapshots repository.