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:
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.
To upload an image file to the HelloSpace application, navigate to the API:
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:
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.
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).
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.
Now, you can verify that the upload worked correctly, by issuing a download API, which is:
where <image-name> is just the name of the file, which you have uploaded without the file name extension.
To download the image:
Navigate to the API and replace the current content of the Request Headers panel with: accept=application/octet-stream.
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.
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.
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.