Blog

Spring boot rest api can be easily configured to upload a single file, multiple files or an object containing both files and other properties. There are a number of ways to create a rest api which can accept a file. We will try to dive in multiple examples here and try to illustrate the difference here. 

Spring boot rest api example is a rest api creation to receive a single or multiple files with Post method. The API method has arguments which should be annotated with either @ResponseBody or @RequestParam. The method should be marked with consume type, either multipart/form-data or multipart/mixed type. For sending api requests via JSON or some programming language, @ResponseBody annotation should be used. If an api request will be submitted via form-data (from Postman) then use @RequestParam.

Prerequisites

To understand spring rest multipart file upload examples in Java, I will try to explain with different examples where you can upload a single file in many ways, upload a list of files, upload as an object or upload a list of objects containing images from Postman. Points to remember for all examples:

1. All examples assume that you already have one controller which is annotated with @RestController annotation.

2. In Postman all requests should have one header named “Content-Type” with value “multipart/form-data”. You can check the following screenshot, for setting this header value.

Example 1: Spring boot multipart file upload example

Create a Rest API in spring boot which consumes the multipart request data. The rest api method should have an input parameter for multipartFile, which will be automatically mapped by Spring. We need to take care of the file parameter’s name, with this same name we will be sending api requests.

Following is the sample API code for this example.

@PostMapping(value = "/example1/upload/file",
     consumes = {MediaType.MULTIPART_FORM_DATA_VALUE},
     produces = {MediaType.APPLICATION_JSON_VALUE} )
public ResponseEntity<String> uploadSingleFileExample1(MultipartFile file) {
  log.info("Request contains, File: " + file.getOriginalFilename());

  // Add your processing logic here
  return ResponseEntity.ok("Success");
}

Now from Postman, we can send the api request, as shown in the example.

Example 2: Spring boot multipart file upload example with @RequestParam

In this example, we are doing the same work as we have done in example 1. The only difference here is the usage of @RequestParam annotation for input argument.

So your rest api code will look something like this.

@PostMapping(value = "/example2/upload/file",
     consumes = {MediaType.MULTIPART_FORM_DATA_VALUE},
     produces = {MediaType.APPLICATION_JSON_VALUE} )
public ResponseEntity<String> uploadSingleFileExample2(@RequestParam MultipartFile file) {
  log.info("Request contains, File: " + file.getOriginalFilename());

  // Add your processing logic here
  return ResponseEntity.ok("Success");
}

There is no change in Postman request, so the earlier postman request will work with it.

Example 3: Spring boot multipart file upload example with @RequestPart

This example is again one another variation of example 1. Here the usage of @RequestPart annotation is shown for input argument. All remaining code will be having no change.

The rest api will look like this now:

@PostMapping(value = "/example3/upload/file",
     consumes = {MediaType.MULTIPART_FORM_DATA_VALUE},
     produces = {MediaType.APPLICATION_JSON_VALUE} )
public ResponseEntity<String> uploadSingleFileExample3(@RequestPart MultipartFile file) {
  log.info("Request contains, File: " + file.getOriginalFilename());

  // Add your processing logic here
  return ResponseEntity.ok("Success");
}

For postman, again there is no change in request, earlier postman requests will be used with api directly without any change.

Example 4: Spring boot multipart file upload example with @RequestBody

This is the fourth variation of example 1. The purpose of these examples is to show you that there are different ways to do a single task. In this example, we have used @RequestBody annotation for input argument in method.

The final code will look like this:

@PostMapping(value = "/example4/upload/file",
     consumes = {MediaType.MULTIPART_FORM_DATA_VALUE},
     produces = {MediaType.APPLICATION_JSON_VALUE} )
public ResponseEntity<String> uploadSingleFileExample4(@RequestBody MultipartFile file) {
  log.info("Request contains, File: " + file.getOriginalFilename());

  // Add your processing logic here
  return ResponseEntity.ok("Success");
}

Even for this example, no change in Postman request. So you can use the earlier created request to test this api.

Example 5: Spring boot multiple files upload example as an Array

Sometimes you need to upload multiple files in a single api request. In this example, we will upload an array of files. In the method input argument, you need to specify an array of MultiPartFile type. Whatever the name of the array you mention here, with the same name from Postman, you have to submit the files.

Following is the sample code to upload an array of files in spring boot rest api.

@PostMapping(value = "/example5/upload/files",
     consumes = {MediaType.MULTIPART_FORM_DATA_VALUE},
     produces = {MediaType.APPLICATION_JSON_VALUE} )
public ResponseEntity<String> uploadFilesExample5(MultipartFile[] files) {
  log.info("Request contains, Files count: " + files.length);

  // Add your processing logic here
  return ResponseEntity.ok("Success");
}

In Postman, we need to select multiple files, but all files should have the same name as the input argument in the rest api. Spring boot will automatically convert to an array for all the files submitted with the same name.In our example, we have array name as “files”, so we will name key name as ‘files’ and select different files.

Example 6: Spring boot multiple files upload example as a List

This example is very similar to example 5. The only difference here is that we will be uploading the list of files instead of array. So lets change input argument to list of MultiPartFile type.

So our code example will look like this now:

@PostMapping(value = "/example6/upload/files",
     consumes = {MediaType.MULTIPART_FORM_DATA_VALUE},
     produces = {MediaType.APPLICATION_JSON_VALUE} )
public ResponseEntity<String> uploadFilesExample6(List<MultipartFile> files) {
  log.info("Request contains, Files count: " + files.size());

  // Add your processing logic here
  return ResponseEntity.ok("Success");
}

In Postman request, there is no change, the api request created in example 5 will work perfectly with example 6. Only change is on the spring boot side, which will map the list of files to list or array, depending upon the type of input argument in method used for creating rest api.

Example 7: Spring boot multipart file upload example as an object

This example is the most common scenario, where you need to upload a file with some additional information. If we create a Java class for this information and try to use the same name in the API request then spring boot will automatically map the request into our Java class.

In this example, we need to upload an image along with a custom title and description. Let’s create a Java class for this and name it as “Gallery”. So the code of “Gallery’ class will look like something this:

public class Gallery {
  private String title;
  private String desc;
  private MultipartFile file;
 
    // Add Getters and setters
}

Now, create one rest api and in the method’s input parameter, use the newly created class “Gallery” as data type. So in our following example, we have “gallery” parameter which has data type “Gallery”

@PostMapping(value = "/example7/upload1",
     consumes = {MediaType.MULTIPART_FORM_DATA_VALUE},
     produces = {MediaType.APPLICATION_JSON_VALUE} )
public String uploadFilesExample7(Gallery gallery) {
  log.info("galleries details: " + gallery);

  // Add your processing logic here
  return "success";
}

In Postman, you need to create multiple keys. Every attribute of the “Gallery” class name will be used as an individual key to submit a request. Your Postman request will look like this:

Example 8: Spring boot multipart file upload example as a list of objects

In this example, we will illustrate to create a rest api for submitting a list of objects where every object contains one or more multipart files. The rest api method will have one input argument for list of objects or you can create another bean which contains a list of objects and use that here.

The rest api code will look like this:

@PostMapping(value = "/example8/upload",
     consumes = {MediaType.MULTIPART_FORM_DATA_VALUE},
     produces = {MediaType.APPLICATION_JSON_VALUE} )
public String uploadFilesExample8(@RequestBody List<Gallery> galleries) {
  log.info("galleries details: "     );

  // Add your processing logic here
  return "success";
}

If you are planning to use Postman to test this api, then you will be disappointed here. As Postman has few limitations and this type of request can’t be sent from Postman. I tried a number of ways but postman does not handle inner level files. But it does not mean, your api is wrong. If you try to invoke this api using any programming language like Javascript, Java etc then you will see that this api works very well.

Conclusion

Spring boot has emerged a lot since the release of this awesome framework. If you don’t mention any annotation for input arguments, even then internally spring boot tries best to map the request to input parameters. I hope these examples will help you somehow. Please feel free to reach me or ask any questions.