2. Tutorials
  3. Retrofit — How to Upload Files to Server

Retrofit — How to Upload Files to Server

This is the last post in our Retrofit series. File upload functionality is often required for mobile apps. Before we start, let’s have an overview of the previously released posts.

Retrofit Series Overview

  1. Getting Started and Creating an Android Client
  2. Basics of API Description
  3. Creating a Sustainable Android Client
  4. URL Handling, Resolution and Parsing
  5. How to Change API Base Url at Runtime
  6. Multiple Server Environments (Develop, Staging, Production)
  7. Share OkHttp Client and Converters between Retrofit Instances
  8. Upgrade Guide from 1.9
  9. Beyond Android: Retrofit for Java Projects
  10. How to use OkHttp 3 with Retrofit 1
  1. Synchronous and Asynchronous Requests
  2. Send Objects in Request Body
  3. Add Custom Request Header
  4. Manage Request Headers in OkHttp Interceptor
  5. Dynamic Request Headers with @HeaderMap
  6. Multiple Query Parameters of Same Name
  7. Optional Query Parameters
  8. Send Data Form-Urlencoded
  9. Send Data Form-Urlencoded Using FieldMap
  10. How to Add Query Parameters to Every Request
  11. Add Multiple Query Parameter With QueryMap
  12. How to Use Dynamic Urls for Requests
  13. Constant, Default and Logic Values for POST and PUT Requests
  14. Cancel Requests
  15. Reuse and Analyze Requests
  16. Optional Path Parameters
  17. How to Send Plain Text Request Body
  18. Customize Network Timeouts
  19. How to Trust Unsafe SSL certificates (Self-signed, Expired)
  20. Dynamic Endpoint-Dependent Interceptor Actions
  21. How to Update Objects on the Server (PUT vs. PATCH)
  22. How to Delete Objects on the Server
  1. Ignore Response Payload with Call<Void>
  2. Receive Plain-String Responses
  3. Crawl HTML Responses with jspoon (Wikipedia Example)
  4. Loading Data into RecyclerView and CardView
  1. Introduction to (Multiple) Converters
  2. Adding & Customizing the Gson Converter
  3. Implementing Custom Converters
  4. How to Integrate XML Converter
  5. Access Mapped Objects and Raw Response Payload
  6. Supporting JSON and XML Responses Concurrently
  7. Handling of Empty Server Responses with Custom Converter
  8. Send JSON Requests and Receive XML Responses (or vice versa)
  9. Unwrapping Envelope Responses with Custom Converter
  10. Wrapping Requests in Envelope with Custom Converter
  11. Define a Custom Response Converter
  1. Simple Error Handling
  2. Error Handling for Synchronous Requests
  3. Catch Server Errors Globally with Response Interceptor
  4. How to Detect Network and Conversion Errors in onFailure
  1. Log Requests and Responses
  2. Enable Logging for Development Builds Only
  3. Log Network Traffic with Stetho and Chrome Developer Tools
  4. Using the Log Level to Debug Requests
  5. Analyze Network Traffic with Android Studio Profiler
  6. Debug and Compare Requests with RequestBin
  1. Introduction to Call Adapters
  2. Custom Call Adapter to Separate OnResponse Callback
  3. How to Integrate RxJava 1.x Call Adapter
  4. How to Integrate RxJava 2.x Call Adapter
  5. How to Integrate Guava Call Adapter
  6. Custom Call Adapter to Separate Network and Gson Errors
  1. Pagination Using Query Parameter
  2. Pagination Using Link Header and Dynamic Urls (Like GitHub)
  3. Pagination Using Range Header Fields (Like Heroku)
  1. Basic Authentication on Android
  2. Token Authentication on Android
  3. OAuth on Android
  4. Hawk Authentication on Android
  5. How to Refresh an Access Token
  1. Activate Response Caching (Etag, Last-Modified)
  2. Check Response Origin (Network, Cache, or Both)
  3. Force Server Cache Support with Response Interceptor
  4. Support App Offline Mode by Accessing Response Caches
  5. Analyze Cache Files
  1. Basics of Mocking Server Responses
  2. Customizing Network Behavior of Mocked Server Responses
  3. Mock APIs with JsonServer
  1. Callbacks
  2. Annotations
  3. Fluent Interface with Builders

Introduction

Most Android apps need some kind of upload functionality where you want to send your profile picture to the server or upload other files to share with your friends. However, this guide can be used for any kind of file and not just images.

File Upload with Retrofit 2.x

We’ve published an updated blog post on how to upload files using Retrofit 2.x. If you’re using Retrofit 2, please follow the linked guide.

Upload Files with Retrofit 1

Retrofit provides the ability to perform Multipart requests. That enables the feature to upload files to a server. The @Multipart annotation is required to perform those requests. The following code shows the method definition to upload a file to a given API endpoint.

public interface FileUploadService {  
    public static final String BASE_URL = "http://your.api/endpoint/base-url";

    @Multipart
    @POST("/upload")
    void upload(@Part("myfile") TypedFile file,
                @Part("description") String description,
                Callback<String> cb);
}

This FileUploadService interface is the client side API declaration. You’re going to request http://your.api/endpoint/base-url/upload hooked with two parameters: a file myfile and String description.

To perform the actual request, you need to instantiate a RestAdapter. Have a look at our Retrofit Getting Started Guide where we present a ServiceGenerator class to create services for defined interfaces.

The ServiceGenerator (described in the getting started post) creates and instantiates the required HTTP client for your service interface. In our case, we pass the FileUploadService to the static method createService and get a functional implementation to perform the upload.

The following code snippet illustrates the usage of previously described methods.

    FileUploadService service = ServiceGenerator.createService(FileUploadService.class, FileUploadService.BASE_URL);
TypedFile typedFile = new TypedFile("multipart/form-data", new File("path/to/your/file"));  
String description = "hello, this is description speaking";

service.upload(typedFile, description, new Callback<String>() {  
    @Override
    public void success(String s, Response response) {
        Log.e("Upload", "success");
    }

    @Override
    public void failure(RetrofitError error) {
        Log.e("Upload", "error");
    }
});

TypedFile is a class from Retrofit representing a file with mime type. We use multipart/form-data as mime type and create a file from given path.

That’s the upload part on Android side :)

Remember the Content-Type

Attention: keep an eye on the content type of the RestAdapter. If you specify the header request.addHeader("Content-Type", "application/json"); via RequestInterceptor, the request will probably fail at server side since your’re sending multipart data and not JSON.

Example hapi.js Server to Handle File Uploads

We’ve tested the upload functionality from Android to the backend with a hapi.js server. For that, we implemented a rudimentary functionality to just log the incoming data at server side. Multiparty was our module of choice for data parsing operations. Of course, you can use whatever you prefer.

The hapi.js route configuration for our file upload test.

server.route([  
    {
        method: 'POST',
                path: '/upload',
            config: {
        payload: {
            maxBytes: 209715200,
                    output: 'stream',
                    parse: false
        },
        handler: function(request, reply) {
            var multiparty = require('multiparty');
            var form = new multiparty.Form();
            form.parse(request.payload, function(err, fields, files) {
                console.log(err);
                console.log(fields);
                console.log(files);
            });
        }
    }
}]);

We want to separate the topics of file upload with Retrofit on Android and the hapi.js server. That’s why we just leave the code snippet above without any additional comments. If you run into any problems or questions regarding the server test code, you can for sure just let us know in the comments or via twitter @futurestud_io.

Nevertheless, here the server log for a successful request.

Server Log for incoming data

null  
{ description: [ 'hello, this is description speaking' ] }
{ myfile:
    [ { fieldName: 'myfile',
        originalFilename: 'IMG-20150311-WA0000.jpg',
        path: '/var/folders/rq/q_m4_21j3lqf1lw48fqttx_80000gn/T/wcvFPnGewEPCm9IHM7ynAS3I.jpg',
        headers: [Object],
    size: 34287 } ] }

The first null log is the err object. Afterwards the description field and finally myfile.

Questions & Problems

Things went south? Just let us know via @futurestud_io or the comments below and we’ll help you get things working.

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous