Junos Space SDK > REST Explorer Guide

Uploading and Downloading Binary Data

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

The REST Explorer provides the following capabilities:

Testing Upload and Download Feature in a Web GUI

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. This exercises the upload feature, using an html/javascript client, which can be found in ImageUpload.html file of the application.

The image download feature is also featured in the HelloSpace application, when the user clicks on a device row in the Device List, the JavaScript code in hellospace.DeviceMasterDetail.ui.js file calls the following API to download the device image:

GET /api/jssdk/hello-space/images/<image-name>

Uploading and Downloading Data with the Explorer

The HelloSpace application can also be used to download and upload images using the REST Explorer. The same APIs that were used to perform these functions in the app's GUI can be used here also.

  1. To upload an image file to the HelloSpace application, navigate to the API:

    POST http://127.0.0.1:8080/api/jssdk/hello-space/images

  2. When uploading data to a POST HTTP Method, the Explorer uses HTTP multipart/form-data protocol, described in Forms in HTML Documents.   When you navigate to a REST API POST method which uses multipart/form-data as Content-Type, the Explorer, automatically, enables the Binary Upload button, which is found to the right of the XML/JSON Template button:

  3. Clicking on the Binary Upload button, presents the user with the File Upload Dialog:

    The dialog contains two fields:

    • Input File—Select binary or unstructured text file to upload to the REST API.

    • Input File Control Name—Optional Control Name for File Select Control.

      Note that currently the Explorer only supports a single part of a multipart/form-data request. This single part can only be a file, and no other part is supported. If you want to test a "true form" submission with multiple parts, you have to implement your own form, using HTML or JavaScript. One has already been implemented for you in the HelloSpace UI, which was described in the previous section.

  4. Select the file to be uploaded from your hard drive by clicking the "Select" button and pick the file to be uploaded. Then click the "Finish" button. However, this will not upload the file. You need to click the green play button in the explorer to have the file uploaded to the REST API.

    Note the name of the file that you have uploaded. Use a simple name for your file (for example, SRX1400.png).

  5. The REST API will return with a 204 No Content status code.  This REST API uses a 204, instead of 200, because, it doesn't have any response body to return.

  6. Now, you can verify that the upload worked correctly, by issuing a download API, which is:

        GET /api/jssdk/hello-space/images/<image-name>

    where <image-name> is just the name of the file, which you have uploaded without the file name extension.

    To download the image:

    1. Navigate to the API and replace the current content of the Request Headers panel with: accept=application/octet-stream.

    2. Click the Explorer's play button again. Now the Explorer fetches the file saved on the server and shows a File Download dialog to save it.

    3. Change the name of the image file from binary_explorer0 to the actual file name you want and click the Save button.

      Note that the Explorer picks an arbitrary name for the file (here it uses binary_explorer0) because, unlike for the case of upload, there is no way to send the file name back to the client along with the data. In this case, the client needs to know the name of the file or retrieve it from the server with another REST API.  The explorer doesn't know the file extension, either, because, the media type which was used in this example was application/octet-stream.  If we had used an explicit binary media type, like image/png or image/jpeg, then the explorer would have filled in the file extension for us.

    4. Open the file just downloaded to verify that its content is the same as what you initially uploaded.

Upload Data Messaging

Input File Control Name is useful only when there are multiple parts in a form submission, and the server code needs to use control names to retrieve them. In most other cases, when you are only using the REST API to upload a file, the server may ignore the Control Name and just extract the first part in the HTTP request.

When uploading files to the server, the Explorer will send the file as a single part but include the uploaded file's name as a filename attribute in the Content-Disposition header of the request. So in effect, the Explorer File Upload Dialog is equivalent to this form:

<form action="http://server.com/cgi/handle" enctype="multipart/form-data" method="post">
   <input name="myfile" type="file">>
   <input value="Send" type="submit">
</form>

If the user selects a file called "file1.gif", the resulting Explorer submission would look like this:

Content-Type: multipart/form-data; boundary=BbC04y

   --BbC04y
   Content-Disposition: file; filename="file1.gif"; name="myfile"
   Content-Type: image/gif
   Content-Transfer-Encoding: binary

   ...contents of file1.gif...
   --BbC04y--

Note how the Input File Control name specified on the Explorer's upload dialog appears in the name attribute of the Content-Disposition header.