retrofit2

Class Retrofit

java.lang.Object

retrofit2.Retrofit

public final class Retrofit
extends Object

Retrofit adapts a Java interface to HTTP calls by using annotations on the declared methods to define how requests are made. Create instances using the builder and pass your interface to create(java.lang.Class<T>) to generate an implementation.

For example,

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

 MyApi api = retrofit.create(MyApi.class);
 Response<User> user = api.getUser().execute();
 

Author:

Bob Lee (bob@squareup.com), Jake Wharton (jw@squareup.com)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Retrofit.Builder Build a new Retrofit.

Method Summary

Modifier and Type	Method and Description
okhttp3.HttpUrl	baseUrl() The API base URL.
CallAdapter<?,?>	callAdapter(Type returnType, Annotation[] annotations) Returns the CallAdapter for returnType from the available factories.
List<CallAdapter.Factory>	callAdapterFactories() Returns a list of the factories tried when creating a callAdapter(Type, Annotation[]) call adapter}.
Executor	callbackExecutor() The executor used for Callback methods on a Call.
okhttp3.Call.Factory	callFactory() The factory used to create OkHttp calls for sending a HTTP requests.
List<Converter.Factory>	converterFactories() Returns an unmodifiable list of the factories tried when creating a request body converter, a response body converter, or a string converter.
<T> T	create(Class<T> service) Create an implementation of the API endpoints defined by the service interface.
Retrofit.Builder	newBuilder()
CallAdapter<?,?>	nextCallAdapter(CallAdapter.Factory skipPast, Type returnType, Annotation[] annotations) Returns the CallAdapter for returnType from the available factories except skipPast.
<T> Converter<T,okhttp3.RequestBody>	nextRequestBodyConverter(Converter.Factory skipPast, Type type, Annotation[] parameterAnnotations, Annotation[] methodAnnotations) Returns a Converter for type to RequestBody from the available factories except skipPast.
<T> Converter<okhttp3.ResponseBody,T>	nextResponseBodyConverter(Converter.Factory skipPast, Type type, Annotation[] annotations) Returns a Converter for ResponseBody to type from the available factories except skipPast.
<T> Converter<T,okhttp3.RequestBody>	requestBodyConverter(Type type, Annotation[] parameterAnnotations, Annotation[] methodAnnotations) Returns a Converter for type to RequestBody from the available factories.
<T> Converter<okhttp3.ResponseBody,T>	responseBodyConverter(Type type, Annotation[] annotations) Returns a Converter for ResponseBody to type from the available factories.
<T> Converter<T,String>	stringConverter(Type type, Annotation[] annotations) Returns a Converter for type to String from the available factories.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public <T> T create(Class<T> service)

Create an implementation of the API endpoints defined by the service interface.

The relative path for a given method is obtained from an annotation on the method describing the request type. The built-in methods are GET, PUT, POST, PATCH, HEAD, DELETE and OPTIONS. You can use a custom HTTP method with @HTTP. For a dynamic URL, omit the path on the annotation and annotate the first parameter with @Url.

Method parameters can be used to replace parts of the URL by annotating them with @Path. Replacement sections are denoted by an identifier surrounded by curly braces (e.g., "{foo}"). To add items to the query string of a URL use @Query.

The body of a request is denoted by the @Body annotation. The object will be converted to request representation by one of the Converter.Factory instances. A RequestBody can also be used for a raw representation.

Alternative request body formats are supported by method annotations and corresponding parameter annotations:

• @FormUrlEncoded - Form-encoded data with key-value pairs specified by the @Field parameter annotation.
• @Multipart - RFC 2388-compliant multipart data with parts specified by the @Part parameter annotation.

Additional static headers can be added for an endpoint using the @Headers method annotation. For per-request control over a header annotate a parameter with @Header.

By default, methods return a Call which represents the HTTP request. The generic parameter of the call is the response body type and will be converted by one of the Converter.Factory instances. ResponseBody can also be used for a raw representation. Void can be used if you do not care about the body contents.

For example:

 public interface CategoryService {
   @POST("category/{cat}/")
   Call<List<Item>> categoryList(@Path("cat") String a, @Query("page") int b);
 }
 

callFactory

public okhttp3.Call.Factory callFactory()

The factory used to create OkHttp calls for sending a HTTP requests. Typically an instance of OkHttpClient.

baseUrl

public okhttp3.HttpUrl baseUrl()

The API base URL.

callAdapterFactories

public List<CallAdapter.Factory> callAdapterFactories()

Returns a list of the factories tried when creating a callAdapter(Type, Annotation[]) call adapter}.

callAdapter

public CallAdapter<?,?> callAdapter(Type returnType,
                                    Annotation[] annotations)

Returns the CallAdapter for returnType from the available factories.

Throws:

IllegalArgumentException - if no call adapter available for type.

nextCallAdapter

public CallAdapter<?,?> nextCallAdapter(@Nullable
                                        CallAdapter.Factory skipPast,
                                        Type returnType,
                                        Annotation[] annotations)

Returns the CallAdapter for returnType from the available factories except skipPast.

Throws:

IllegalArgumentException - if no call adapter available for type.

converterFactories

public List<Converter.Factory> converterFactories()

Returns an unmodifiable list of the factories tried when creating a request body converter, a response body converter, or a string converter.

requestBodyConverter

public <T> Converter<T,okhttp3.RequestBody> requestBodyConverter(Type type,
                                                                 Annotation[] parameterAnnotations,
                                                                 Annotation[] methodAnnotations)

Returns a Converter for type to RequestBody from the available factories.

Throws:

IllegalArgumentException - if no converter available for type.

nextRequestBodyConverter

public <T> Converter<T,okhttp3.RequestBody> nextRequestBodyConverter(@Nullable
                                                                     Converter.Factory skipPast,
                                                                     Type type,
                                                                     Annotation[] parameterAnnotations,
                                                                     Annotation[] methodAnnotations)

Returns a Converter for type to RequestBody from the available factories except skipPast.

Throws:

IllegalArgumentException - if no converter available for type.

responseBodyConverter

public <T> Converter<okhttp3.ResponseBody,T> responseBodyConverter(Type type,
                                                                   Annotation[] annotations)

Returns a Converter for ResponseBody to type from the available factories.

Throws:

IllegalArgumentException - if no converter available for type.

nextResponseBodyConverter

public <T> Converter<okhttp3.ResponseBody,T> nextResponseBodyConverter(@Nullable
                                                                       Converter.Factory skipPast,
                                                                       Type type,
                                                                       Annotation[] annotations)

Returns a Converter for ResponseBody to type from the available factories except skipPast.

Throws:

IllegalArgumentException - if no converter available for type.

stringConverter

public <T> Converter<T,String> stringConverter(Type type,
                                               Annotation[] annotations)

Returns a Converter for type to String from the available factories.

callbackExecutor

@Nullable
public Executor callbackExecutor()

The executor used for Callback methods on a Call. This may be null, in which case callbacks should be made synchronously on the background thread.

newBuilder

public Retrofit.Builder newBuilder()