Sending and debugging binary data in Postman requests

Ian Douglas

November 30, 2023

Postman has come a long way to becoming the comprehensive platform that allows developers to test and build APIs of different frameworks and architectures like RESTful, GraphQL, Asynchronous, and gRPC. While modern APIs predominantly use text-based formats like JSON to exchange data, there are times when binary data needs to be sent, such as uploading an image or a file. Let’s look at the intricacies of sending binary data in a POST request using Postman, how to set the correct headers, and debugging with the Postman Console. In this blog post, we’ll cover RESTful and asynchronous APIs.

Sending binary data for RESTful APIs

RESTful APIs are the most widespread API architectural style. When sending binary data through a POST request in a RESTful API using Postman, only a few steps are needed:

1. Select the HTTP Method: In Postman, select POST as your HTTP method for your request.
2. Enter the URL: Input the endpoint URL where you are transmitting data.
3. Choose Body tab: Click on the Body tab, and select binary from the dropdown menu.
4. Upload the file: Click on the Select File button, and your operating system will prompt you to choose a file.
5. Setting headers: You will need to set the Content-Type header when sending binary data, and should match the data type you are transmitting. For example, if you are sending a JPEG image, your Content-Type header should be set to image/jpeg. Postman will attempt to set this header for you, but double-check that it is set correctly. The Content-Length header will be calculated by Postman automatically before you transmit the data.
6. Send your request: You can click the Send button, or you use the keyboard shortcut, typically Cmd-Enter on a Mac, or Ctrl-Enter on Windows/Linux systems.

Asynchronous APIs: managing binary data

Asynchronous APIs, commonly linked with WebSockets, allow continuous data flow between the client and server. Postman’s WebSocket capability enables binary data transmission for these APIs as well.

It’s important to note that WebSockets transmit data in “frames,” and each frame of data contains the header information and a portion of the data you’re transmitting. Your application typically does not need to do the low-level work of building or decoding these frames, as it’s typically handled within library code. The WebSocket protocol makes no assumptions about the format of each message. There is a single bit which tracks whether the message contains text or binary data, making it very easy for clients and servers to decode the message properly.

However, Postman sends WebSocket data as text-only to guarantee compatibility, as browsers universally handle text-based transmissions. Postman does not directly send binary data over WebSocket connections. We recommend using a conversion format such as Base64 encoding to convert binary data into text format. There are many common tools and libraries available to do this conversion for you.

To get started with WebSockets in Postman, click on the New button at the top of the interface, select WebSocket, and then follow these steps:

1. Set the URL: Start with ws:// (or wss:// for secure connections).
2. Connect to the WebSocket connection: Once connected, choose the message type as Binary and choose Base64 or Hexadecimal as the message format. There are no additional headers to send the binary data in this format.
3. Send the binary data: Click the Send button. If your WebSocket server allows it, you can click Send over and over as I do in the animation below.
4. Disconnect from the server: Click on the Disconnect button to close the connection between you and the server.

In the example below, I’m pasting in a Base64-encoded representation of the Postman logo:

Debugging with the Postman Console

Whether your API call is RESTful or asynchronous, things might not go as planned. The Postman Console is a great tool to use to debug problems. Here are some common steps for using the console to determine why something didn’t work as expected.

1. Open the Postman Console: You’ll find a small toolbar at the bottom of the Postman interface, where you’ll find the Postman Console. Click on Console to open the panel.
2. View request and response: Every request you send via Postman will appear in the console, along with its response. Look for any errors or unexpected behaviors.
3. Filter results: Use the filtering options to narrow down your search. This is particularly handy when dealing with multiple requests.
4. Inspect headers: Ensure the headers align with what the API expects. The console displays both request and response headers.

Managing headers, request types, and body formats can be a lot, but Postman makes it much easier. If you look at the generated documentation that Postman creates for your requests, you’ll see that Postman even writes some code in a few popular programming languages to get you started. Once you have your code written, using your own debugger is also a great source of information on what’s happening in your application if something doesn’t work as expected.

Conclusion

As developers and testers continue to explore the vast landscapes of APIs, the need for versatile tools is undeniable. Postman stands out not just as an HTTP client but as a comprehensive platform tailored to the demands of modern API testing and development. Teams can build entire workspaces with collections of requests from all kinds of API architectures and frameworks. Sending binary data, despite its complexities, becomes less scary with Postman. Whether you’re working with the ubiquity of RESTful APIs, or the real-time nature of asynchronous APIs, Postman’s environment and console for debugging ensures you and your team are always in control.