Junos Space SDK > REST Explorer Guide

RESTifying APIs that Upload or Download Binary Data

This topic explains how to create REST APIs which upload and download binary data using the SDK REST Wizard.  The APIs which allow clients to upload binary data use the multipart/form-data as the media type for Content-type header.  The APIs which download binary data can use any standard media type which supports binary data, such as image/png, image/jpg or application/octet-stream.

The REST Wizard provides the following capabilities:

Creating a Binary Upload POST Method using the Wizard

  1. To test both the upload and download features, you can use the HelloSpace Reference Application which was installed by the SDK installer in your Juniper Networks folder. Install the application on your server and try uploading an image file using the "Upload Device Image" task of the application's GUI or use the REST Explore for Uploading and Downloading Binary Data.  The REST Explorer example covers client usage of the HelloSpace's binary file upload and download capabilities.
  1. Now study the HelloSpace EJB code. You will find the file upload method with the following signature:

  2. public void addImage(byte[] imageFileBytes, String imageFile) throws Exception;
    
  3. Go to the wizard to RESTify this method.  Note that the method may have already been RESTified, so you may want to unrestify it, and RESTify it again.  After selecting the method in the method's table, and clicking the REST+ button, the Configure REST Method dialog comes up, displaying the following configuration for the addImage method:

    In the screenshot above, notice that the second parameter of the EJB method (which is the imageFile) is taken to be the @Query parameter by the wizard and the first parameter (which is the binary data) is correctly identified by the wizard as multi-part with the media type of multipart/form-data. The default configuration displayed here can be useful if the client had no way to identify the file name, other than pass the query parameter to the REST method. However, in most cases, this REST API will be called from an HTTP Form submission, which will pass the file name together with the file content in the multipart disposition header. This is described in the Multi Part Form Submission W3C document and also in the REST Explorer Guide's Uploading and Downloading Binary Data.

  4. So what we need to do is to move the @Query parameter to be the @Body parameter by right-clicking on the Category row in the Request Parameters table, and selecting @Body in the drop-down.  Now the two parameters will be together in the Request Message Body table:

    Now the Request Message Body table shows that both the image file name and its content will be uploaded in a single multipart request.

  5. The multipart request used by the HelloSpace client (which is a form), will be sent to the server as a single part, not as two parts.  The request will consist of the binary data stream in the first part, and the filename encoded in the Content-Disposition header of the first part.  To configure the filename in the Content-Disposition header, we edit the image-file parameter and check the "Use filename property in the Content-Disposition header?" checkbox.


  6. Note that this dialog also has the "Part Name" text box to specify if the server code will use the part name from the request or fetch the data in sequence order.  Usually, the part names of an HTML form correspond to the control names of the form controls.  In this case, since, there is only a single part, there is no need to fill in the "Part Name" text box. Also note that the second parameter image-file-bytes can also be edited, and a "Part Name" specified for it.  Again, there is no need to do it because we only have one part in this request.

  7. We are now done with the multipart configuration.  We can save the configuration and exit the wizard.  Once the wizard has generated the code, please examine the generated REST code in HelloSpaceRestImpl.java of HelloSpaceWebSvc project's web-src folder. As an additional exercise, you may also want to specify various values of "Part Name" and Content-Disposition checkbox and examine the changes to the code.

  8. After generating the code, deploy your application and test it, either by using the REST Explorer or a real form in the HelloSpace's "Upload Device Image" task.

The response from the binary upload POST method generated by the wizard will depend on the return value of the source EJB method. If the method return value is present, then regular processing will be applied, where the user is asked to pick a Media Type name, representation, and other configuration options. Note that the POST method can also be used for both uploading and downloading.

If the wizard detects that the EJB method returns a binary type, it will use a binary Media Type for the response.  Default media type set by the wizard for binary response is application/octet-stream. This media type represents any binary data which may be returned by the REST method.

Of course, you can modify the media type, if you want something else, such as image/png or image/jpeg or any other binary media type.  These media types limit the binary format of the data in the response to .png only or .jpg only.

Creating a Binary Download GET Method using the Wizard

The HelloSpace application also includes a getImage() method, which is used to download binary data form the server. The method signature looks like this:

public byte [] getImage(String platform) throws Exception;
  1. RESTify this method and change the following configuration:

    1. Change Category for platform parameter from @Query(platform) to @Path(platform).
    2. Edit the Resource Path to say /images/{platform} as shown in the the following image.
  2. After changing those two parameters, we can proceed with the code generation and testing, using the SDK Explorer or with theHelloSpace application itself.