- RxJava 2.x is now supported with a first-party 'adapter-rxjava2' artifact.
@QueryNameannotation allows creating a query parameter with no '=' separator or value.
- New: Support for messages generated by Protobuf 3.0 or newer when using the converter for Google's protobuf.
- New: RxJava 1.x call adapter now correctly handles broken subscribers whose methods throw exceptions.
- New: Add
- New: The Moshi converter factory now offers methods for enabling null serialization and lenient parsing.
- New: Add
createAsync()to RxJava 1.x call adapter factory which executes requests using
Call.enqueue()using the underlying HTTP client's asynchronous support.
NetworkBehaviornow allows setting an error percentage and returns HTTP errors when triggered.
HttpExceptionhas been moved into the main artifact and should be used instead of the versions embedded in each adapter (which have been deprecated).
- Promote the response body generic type on
adaptmethod to the enclosing class. This is a source-incompatible but binary-compatible change which is only relevant if you are implementing your own
- Remove explicit handling of the now-defunct RoboVM platform.
- Fix: Close response on HTTP 204 and 205 to avoid resource leak.
- Fix: Reflect the canceled state of the HTTP client's
- Fix: Use supplied string converters for the
Stringtype on non-body parameters. This allows user converters to handle cases such as when annotating string parameters instead of them always using the raw string.
- Fix: Skip a UTF-8 BOM (if present) when using the converter for Moshi.
@HeaderMapannotation and support for supplying an arbitrary number of headers to an endpoint.
@JsonAdapterannotations on the
@Bodyparameter and on the method will be propagated to Moshi for creating the request and response adapters, respectively.
- Fix: Honor the
Content-Typeencoding of XML responses when deserializing response bodies.
- Fix: Remove the stacktrace from fake network exceptions created from retrofit-mock's
NetworkBehavior. They had the potential to be misleading and look like a library issue.
- Fix: Eagerly catch malformed
Content-Typeheaders supplied via
ProtoConverterFactory.createWithRegistry()method accepts an extension registry to be used when deserializing protos.
- Fix: Pass the correct
onFailuremethods such that calling
clone()retains the correct threading behavior.
- Fix: Reduce the per-request allocation overhead for the RxJava call adapter.
- New: Support OkHttp's
- New: Support iterable and array
@Partparameters using OkHttp's
- Fix: Honor backpressure in
Observables created from the RxJavaCallAdapterFactory.
- New: Support OkHttp's
🚀 Retrofit 2 is a major release focused on extensibility. The API changes are numerous but solve shortcomings of the previous version and provide a path for future enhancement.
🚀 Because the release includes breaking API changes, we're changing the project's package name from
retrofit2. This should make it possible for large applications and libraries to migrate incrementally. The Maven group ID is now
com.squareup.retrofit2. For an explanation of 👀 this strategy, see Jake Wharton's post, Java Interoperability Policy for Major Version ⚡️ Updates.
Service methods return
Call<T>. This allows them to be executed synchronously or asynchronously using the same method definition. A
Callinstance represents a single request/response pair so it can only be used once, but you can
clone()it for re-use. Invoking
cancel()will cancel in-flight requests or prevent the request from even being performed if it has not already.
Multiple converters for multiple serialization formats. API calls returning different formats (like JSON, protocol buffers, and plain text) no longer need to be separated into separate service interfaces. Combine them together and add multiple converters. Converters are chosen based on the response type you declare. Gson is no longer included by default, so you will always need to add a converter for any serialization support. OkHttp's
ResponseBodytypes can always be used without adding one, however.
Call adapters allow different execution mechanisms. While
Callis the built-in mechanism, support for additional ones can be added similar to how different converters can be added. RxJava's
Observablesupport has moved into a separate artifact as a result, and support for Java 8's
ListenableFutureare also provided as additional artifacts.
Generic response type includes HTTP information and deserialized body. You no longer have to choose between the deserialized body and reading HTTP information. Every
Callautomatically receives both via the
Response<T>type and the RxJava, Guava, and Java 8 call adapters also support it.
@Url for hypermedia-like APIs. When your API returns links for pagination, additional resources, or updated content they can now be used with a service method whose first parameter is annotated with
🔄 Changes from beta 4:
RxJavaCallAdapterFactorynow supports service methods which return
Completablewhich ignores and discards response bodies, if any.
RxJavaCallAdapterFactorysupports supplying a default
Schedulerwhich will be used for
MoshiConverterFactorysupports creating an instance which uses lenient parsing.
@Partcan omit the part name and use OkHttp's
MultipartBody.Parttype for supplying parts. This lets you customize the headers, name, and filename and provide the part body in a single argument.
BaseUrlinterface and support for changeable base URLs was removed. This functionality can be done using an OkHttp interceptor and a sample showcasing it was added.
Response.isSuccess()was renamed to
Response.isSuccessful()for parity with the name of OkHttp's version of that method.
- Fix: Throw a more appropriate exception with a message when a resolved url (base URL + relative URL) is malformed.
GsonConverterFactorynow honors settings on the
Gsoninstance (like leniency).
ScalarsConverterFactorynow supports primitive scalar types in addition to boxed for response body parsing.
Retrofit.callbackExecutor()may now return an executor even when one was not explicitly provided. This allows custom
CallAdapter.Factoryimplementations to use it when triggering callbacks to ensure they happen on the appropriate thread for the platform (e.g., Android).
Callinstance is now passed to both
Callback. This aids in detecting when
onFailureis called as a result of
Call.request()returns (optionally creating) the
Requestobject for the call. Note: If this is called before
Call.enqueue()this will do relatively expensive work synchronously. Doing so in performance-critical sections (like on the Android main thread) should be avoided.
- New: Support for the release version of OkHttp 3.0 and newer.
adapter-guavamodule provides a
adapter-java8module provides a
CallAdapter.Factoryfor Java 8's
converter-scalarsmodule) now supports parsing response bodies into either
String, the 8 primitive types, or the 8 boxed primitive types.
- New: Automatic support for sending callbacks to the iOS main thread when running via RoboVM.
- New: Method annotations are now passed to the factory for request body converters. This allows converters to alter the structure of both request bodies and response bodies with a single method-level annotation.
- Each converter has been moved to its own package under
retrofit2.converter.<name>. This prevents type collisions when many converters are simultaneously in use.
- Fix: Exceptions thrown when unable to locate a
CallAdapter.Factoryfor a method return type now correctly list the
- Fix: Ensure default methods on service interfaces can be invoked.
- Fix: Correctly resolve the generic parameter types of collection interfaces when subclasses of those collections are used as method parameters.
- Fix: Do not encode
encoded = true.
- New: All classes have been migrated to the
retrofit2.*package name. The Maven groupId is now
com.squareup.retrofit2. This is in accordance with the Java Interoperability Policy for Major Version Updates. With this change Retrofit 2.x can coexiest with Retrofit 1.x in the same project.
- New: Update to use the OkHttp 3 API and OkHttp 3.0.0-RC1 or newer is now required. Similar to the previous
point, OkHttp has a new package name (
okhttp3.*) and Maven groupId (
com.squareup.okhttp3) which allow it to coexist with OkHttp 2.x in the same project.
- New: String converters allow for custom serialization of parameters that end up as strings (such as
Converter.Factoryhas a new
stringConvertermethod which receives the parameter type and annotations and can return a converter for that type. This allows providing custom rendering of types like
User, etc. to a string before being used for its purpose. A default converter will call
toString()for any type which retains the mimics the previous behavior.
- New: OkHttp's
Call.Factorytype is now used as the HTTP client rather than using the
OkHttpClienttype directly (
callFactorymethod has been added to both
Retrofitto allow supplying alternate implementations of an HTTP client. The
Retrofit.Builderstill exists as a convenience.
isExecuted()method returns whether a
Callhas been synchronously or asynchronously executed.
isCanceled()method returns whether a
Callhas been canceled. Use this in
onFailureto determine whether the callback was invoked from cancellation or actual transport failure.
converter-scalarsmodule provides a
String, the 8 primitive types, and the 8 boxed primitive types as
text/plainbodies. Install this before your normal converter to avoid passing these simple scalars through, for example, a JSON converter.
Converter.Factorymethods now receive a
Retrofitinstance which also now has methods for querying the next converter for a given type. This allows implementations to delegate to others and provide additional behavior without complete reimplementation.
@OPTIONSannotation more easily allows for making OPTIONS requests.
@Partannotation now supports
Listand array types.
- New: The
@Urlannotation now allows using
android.net.Uri(in addition to
String) as parameter types for providing relative or absolute endpoint URLs dynamically.
- New: The
retrofit-mockmodule has been rewritten with a new
BehaviorDelegateclass for implementing fake network behavior in a local mock implementation of your service endpoints. Documentation and more tests are forthcoming, but the
SimpleMockServicedemonstrates its use for now.
- Fix: Forbid Retrofit's
Responsetype and OkHttp's
Responsetype as the response body type given to a
ResponseBodytype is the correct one to use when the raw body contents are desired.
- Fix: The Gson converter now respects settings on the supplied
Gsoninstance (such as
serializeNulls). This requires Gson 2.4 or newer.
- The Wire converter has been updated to the Wire 2.0 API.
- The change in 2.0.0-beta2 which provided the
Retrofitinstance to the
Callbackhas been reverted. There are too many edge cases around providing the
Retrofitobject in order to allow deserialization of the error body. To accommodate this use case, pass around the
Retrofitresponse manually or implement a custom
CallAdapter.Factorydoes so automatically.
- New: All classes have been migrated to the
- New: Using a response type of
Call<Void>) will ignore and discard the response body. This can be used when there will be no response body (such as in a 201 response) or whenever the body is not needed.
@Headrequests are now forced to use this as their response type.
Retrofit.Builderwill verify the correctness of all service methods on calls to
create()instead of lazily validating on first use.
Converteris now parameterized over both 'from' and 'to' types with a single
Converter.Factoryis now an abstract class and has factory methods for both request body and response body.
CallAdapter.Factorynow receive the method annotations when being created for a return/response type and the parameter annotations when being created for a parameter type.
Retrofitallows querying a
CallAdapterfor a given type. The
nextCallAdapter()method allows delegating to another
CallAdapterfrom within a
CallAdapter.Factory. This is useful for composing call adapters to incrementally build up behavior.
Retrofitallow querying a
Converterfor a given type.
Callbacknow receives the
Retrofitinstance. Combined with the
Retrofit, this provides a way of deserializing an error body on
Response. See the
DeserializeErrorBodysample for an example.
- New: The
MoshiConverterFactoryhas been updated for its v1.0.0.
- Fix: Using
ResponseBodyfor the response type or
RequestBodyfor a parameter type is now correctly identified. Previously these types would erroneously be passed to the supplied converter.
- Fix: The encoding of
@Pathvalues has been corrected to conform to OkHttp's
- Fix: Use form-data content disposition subtype for
Single-based execution of requests now behave synchronously (and thus requires
subscribeOn()for running in the background).
- Fix: Correct
GsonConverterFactoryto honor the configuration of the
Gsoninstances (such as not serializing null values, the default).
- New: Using a response type of
Callencapsulates a single request/response HTTP call. A call can by run synchronously via
execute()or asynchronously via
enqueue()and can be canceled with
Responseis now parameterized and includes the deserialized body object.
@Urlparameter annotation allows passing a complete URL for an endpoint.
- New: OkHttp is now required as a dependency. Types like
TypedOutput(and its implementations),
Headerhave been replaced with OkHttp types like
Factory) provides extension point for supporting multiple execution mechanisms. An RxJava implementation is provided by a sibling module.
Factory) provides extension point for supporting multiple serialization mechanisms. Gson, Jackson, Moshi, Protobuf, Wire, and SimpleXml implementations are provided by sibling modules.
- Fix: A lot of things.
- Hello Droidcon NYC 2015!
- Update to OkHttp 2.x's native API. If you are using OkHttp you must use version 2.0 or newer (the latest
is 2.2 at time of writing) and you no longer need to use the
- New: Allow disabling Simple XML Framework's strict parsing.
@Headernow accepts a
Listor array for a type.
@FieldMapnow have options for enabling or disabling URL encoding of names and values.
- Fix: Remove query parameters from thread name when running background requests for asynchronous use.
- Update to OkHttp 2.x's native API. If you are using OkHttp you must use version 2.0 or newer (the latest is 2.2 at time of writing) and you no longer need to use the