What is Payload in REST API? How to send Payload using HTTP Post Request and HttpClient

Hello and welcome to the blog post. In this comprehensive article we are going to take a look at an interesting topic. I’m sure you all are familiar with client-server architecture. If not let me recap it quickly for you. 

A Client is a machine (or a web-browser) that request for desired results from the  server. In other words, clients initiate requests for services or resources, while servers provide those services or resources upon request. The client-server model forms the foundation of many networked applications and systems, where clients and servers communicate and collaborate to fulfill various tasks and deliver services.

What is a Payload?

When a client sends a request to a server, the payload typically contains the data or parameters required by the server to process the request. For example, in a client-server architecture for a web application, the payload of an HTTP request sent by the client may include parameters for a form submission, JSON data for an API request, or a file to be uploaded.

On the server side, when the server sends a response back to the client, the payload contains the data or information requested by the client. This can include HTML content, JSON responses, file attachments, or any other data relevant to the specific request made by the client.

Payload in REST API

The information supplied in the body of an HTTP request is referred to as a payload in the RESTful API architecture. It represents the data that is being sent from the client to the server or the other way around. Depending on the content type supplied in the request headers, the payload may be in one of several forms, including JSON, XML, or plain text.

The payload carries the necessary data required to perform operations on the server or to retrieve specific resources. For example, when creating a new resource, the payload would typically contain the data that needs to be stored on the server. When updating an existing resource, the payload would include the modified data.

What is an HttpClient? 

HttpClient is a powerful Java package that offers quick and efficient way for submitting HTTP requests and receiving server responses. Starting with Java 11, it is a part of the Java SE standard library and offers a comprehensive API for interacting with HTTP-based services.

HttpClient's main objective is to make it easier for client applications to communicate with RESTful APIs, web services, and other HTTP-based endpoints. The low-level aspects of creating and managing connections, dealing with request and response bodies, modifying headers, controlling timeouts, and dealing with redirection are abstracted away.

You can perform various HTTP operations like GET, POST, PUT, DELETE by using HttpClient. It supports both synchronous and asynchronous request processing and offers a number of configuration options for customization.

Let’s take an example on how to send a POST request to REST API using HttpClient

import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;

import java.net.http.HttpClient;

import java.net.http.HttpRequest;

import java.net.http.HttpResponse;

import java.net.http.HttpHeaders;

import java.net.http.HttpResponse.BodyHandlers;

public class HttpClientExample {

    public static void main(String[] args) throws Exception {

        // Create an instance of HttpClient

        HttpClient httpClient = HttpClient.newHttpClient();

        // Define the URL of the REST API endpoint

        String url = "http://api.example.com/users";

        // Create a User object

        User user = new User("John Doe", 30);

        // Serialize the User object to JSON

        ObjectMapper objectMapper = new ObjectMapper();

        String requestBody = objectMapper.writeValueAsString(user);

        // Build the HTTP request

        HttpRequest request = HttpRequest.newBuilder()

                .uri(URI.create(url))

                .header("Content-Type", "application/json")

                .POST(HttpRequest.BodyPublishers.ofString(requestBody))

                .build();

        // Send the request and receive the response

        HttpResponse<String> response = httpClient.send(request, BodyHandlers.ofString());

        // Extract the User object from the response

        String responseBody = response.body();

        User responseUser = objectMapper.readValue(responseBody, User.class);

        // Print the response User object

        System.out.println("Response User: " + responseUser);

    }

}

class User {

    private String name;

    private int age;

    // Constructors, getters, and setters

    @Override

    public String toString() {

        return "User{" +

                "name='" + name + '\'' +

                ", age=" + age +

                '}';

    }

}

In this example, we have a User class representing the user object. We use the ObjectMapper from the Jackson library to serialize the User object to JSON format. 

We then create an HttpRequest object with the necessary details, including the URI, headers (in this case, "Content-Type" is set to "application/json"), and the request body containing the serialized User object. 

After sending the request using httpClient.send(), we receive the response as an HttpResponse object. We extract the response body as a JSON string. 

Finally, we deserialize the response JSON string back into a User object using objectMapper.readValue(). The resulting User object represents the response payload, which we can use as needed.

Sending Payload to REST API using HTTP POST Request and HttpClient in Java

import java.net.URI;

import java.net.http.HttpClient;

import java.net.http.HttpRequest;

import java.net.http.HttpResponse;

import java.net.http.HttpHeaders;

import java.net.http.HttpEntity;

import java.net.http.HttpHeaders;

import java.net.http.HttpRequest.BodyPublishers;

import java.net.http.HttpResponse.BodyHandlers;

public class HttpClientExample {

    public static void main(String[] args) throws Exception {

        HttpClient httpClient = HttpClient.newHttpClient();

        String jsonPayload = "{\"name\": \"Someone \", \"email\": \"someone@example.com\"}";

        HttpRequest request = HttpRequest.newBuilder()

                .uri(URI.create("http://example.com/api/resource"))

                .header("Content-Type", "application/json")

                .POST(BodyPublishers.ofString(jsonPayload))

                .build();

        HttpResponse<String> response = httpClient.send(request, BodyHandlers.ofString());

        int statusCode = response.statusCode();

        String responseBody = response.body();

        System.out.println("Status Code: " + statusCode);

        System.out.println("Response Body: " + responseBody);

    }

}

In the example above, we create a JSON payload using a sample data object. We set the HTTP method to POST, the request URL to "http://example.com/api/resource", and the content type to "application/json". The payload is then sent in the body of the request using the BodyPublishers.ofString() method. 

Finally, we retrieve and handle the response from the server.

Remember to replace "http://example.com/api/resource" with the actual endpoint URL of the REST API you want to send the payload to, and modify the payload data according to your requirements and the API's expected format.

Let me show you how to send other types of payloads from the following example.

1) Sending a Form-UrlEncoded Payload

import java.net.URI;

import java.net.http.HttpClient;

import java.net.http.HttpRequest;

import java.net.http.HttpResponse;

import java.net.http.HttpHeaders;

import java.net.http.HttpEntity;

import java.net.http.HttpHeaders;

import java.net.http.HttpRequest.BodyPublishers;

import java.net.http.HttpResponse.BodyHandlers;

import java.net.URLEncoder;

import java.nio.charset.StandardCharsets;

public class HttpClientExample {

    public static void main(String[] args) throws Exception {

        HttpClient httpClient = HttpClient.newHttpClient();

        String payload = "name=" + URLEncoder.encode("John Doe", StandardCharsets.UTF_8)

                + "&email=" + URLEncoder.encode("johndoe@example.com", StandardCharsets.UTF_8);

        HttpRequest request = HttpRequest.newBuilder()

                .uri(URI.create("http://example.com/api/resource"))

                .header("Content-Type", "application/x-www-form-urlencoded")

                .POST(BodyPublishers.ofString(payload))

                .build();

        HttpResponse<String> response = httpClient.send(request, BodyHandlers.ofString());

        int statusCode = response.statusCode();

        String responseBody = response.body();

        System.out.println("Status Code: " + statusCode);

        System.out.println("Response Body: " + responseBody);

    }

}

In this example, we are sending a form-urlencoded payload to the REST API endpoint "http://example.com/api/resource". The payload contains two fields, name and email, which are URL-encoded using the URLEncoder.encode() method. The Content-Type header is set to "application/x-www-form-urlencoded".

2) Sending a Plain Text Payload

import java.net.URI;

import java.net.http.HttpClient;

import java.net.http.HttpRequest;

import java.net.http.HttpResponse;

import java.net.http.HttpHeaders;

import java.net.http.HttpEntity;

import java.net.http.HttpHeaders;

import java.net.http.HttpRequest.BodyPublishers;

import java.net.http.HttpResponse.BodyHandlers;

public class HttpClientExample {

    public static void main(String[] args) throws Exception {

        HttpClient httpClient = HttpClient.newHttpClient();

        String textPayload = "This is a plain text payload.";

        HttpRequest request = HttpRequest.newBuilder()

                .uri(URI.create("http://example.com/api/resource"))

                .header("Content-Type", "text/plain")

                .POST(BodyPublishers.ofString(textPayload))

                .build();

        HttpResponse<String> response = httpClient.send(request, BodyHandlers.ofString());

        int statusCode = response.statusCode();

        String responseBody = response.body();

        System.out.println("Status Code: " + statusCode);

        System.out.println("Response Body: " + responseBody);

    }

}

In this example, we are sending a plain text payload to the REST API endpoint "http://example.com/api/resource". The payload simply contains the text "This is a plain text payload." The Content-Type header is set to "text/plain" to indicate that the payload is in plain text format.

Summary 

In summary, sending a payload to a REST API using an HTTP POST request and HttpClient in Java involves creating an HTTP request with the desired payload, specifying the necessary headers, and sending the request using the HttpClient instance. The server will process the payload and provide a response, which can be accessed and utilized accordingly.