What is Payload in REST API?

📘 Premium Read: Access my best content on Medium member-only articles — deep dives into Java, Spring Boot, Microservices, backend architecture, interview preparation, career advice, and industry-standard best practices.

✅ Some premium posts are free to read — no account needed. Follow me on Medium to stay updated and support my writing.

🎓 Top 10 Udemy Courses (Huge Discount): Explore My Udemy Courses — Learn through real-time, project-based development.

▶️ Subscribe to My YouTube Channel (172K+ subscribers): Java Guides on YouTube

In the realm of REST APIs, the term "payload" plays a crucial role. Payloads refer to the actual data sent by the client in a request to the server or returned by the server in response. This data can be in various formats such as JSON, XML, or even binary data like images or videos. Understanding the concept of payloads and how they are utilized in different HTTP methods is fundamental for effective API development and integration.

What is Payload in REST API?

In a REST API, a payload refers to the data or information sent by the client in a request to the server or the data returned by the server in response to a client request. The payload typically contains data that needs to be processed or manipulated by the server, such as a JSON or XML object or sometimes binary data like images or videos.

For example, when a client sends a POST request to a server to create a new resource, the payload typically contains the data for that resource in JSON or XML format. Similarly, when a client sends a PUT request to update an existing resource, the payload will contain the updated data for that resource.

The payload is an essential part of a REST API as it contains the actual data being transferred between the client and the server. To ensure proper communication and data handling, it is important to ensure that the payload is properly formatted and structured according to the API's specifications.

JSON payload format example:

{
    "cid": 1,
    "cname": "Ramesh",
    "email": "ramesh@gmail.com"
}

XML payload format example:

<customer>
   <cid>1</cid>
   <cname>Ramesh</cname>
   <email>ramesh@gmail.com</email>
</customer>

Payload Composition

Content

The payload carries data, which can be structured in various formats such as JSON, XML, or even plain text. In the realm of RESTful APIs, JSON remains the most popular choice due to its lightweight nature and ease of use.

HTTP Headers

Accompanying the payload are HTTP headers, which provide meta-information about the payload, such as its type (Content-Type header, e.g., application/json) and length (Content-Length header).

The Content-Type header in the HTTP request message represents the payload format in the HTTP request message. For example, JSON, XML, etc.

The Accept The header in an HTTP request message represents the expected payload format in an HTTP response message. Examples include JSON, XML, plain text, HTML, etc.

Payload in Different HTTP Methods

• GET: Typically, GET requests fetch data. While these requests do not usually have a request body (payload), some advanced APIs might use the body to send extensive search or filter criteria.
• POST: When creating a new resource, the payload usually carries data for the new entity.
• PUT: Used to update a resource, the payload here encompasses the complete updated data.
• PATCH: This method is for partial updates, and the payload contains only specific fields meant for modification.
• DELETE: While DELETE operations commonly don't have a payload, some APIs expect additional deletion-related data in the request body.

HTTP Request and Response Payload JSON Example

HTTP Request Message Example:

An HTTP request message with a JSON payload is typically structured with:

• A request line includes the HTTP method, the request URI, and the HTTP version.
• Headers that provide meta-information about the request.
• A blank line indicates the end of the headers.
• The message body, which contains the JSON payload.

Let's consider an example. Imagine you are developing a RESTful API for managing a collection of books and want to add a new book to it.

HTTP Request Example:

POST /api/books HTTP/1.1
Host: www.example.com
User-Agent: Mozilla/5.0
Accept: application/json
Content-Type: application/json
Content-Length: 112

{
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald",
  "year": 1925,
  "genre": "Fiction"
}

Explanation:

Request Line:

• POST is the HTTP method indicating we want to create a new resource.
• /api/books is the request URI specifying the endpoint we're targeting.
• HTTP/1.1 is the HTTP version.

Headers:

• Host: Specifies the domain name of the server.
• User-Agent: Indicates the client's software (e.g., a web browser or other client).
• Accept: Tells the server the type of data the client is expecting in response.
• Content-Type: Specifies the media type of the data being sent to the server, which in this case is application/json.
• Content-Length: Indicates the length of the request body.

Blank Line: This separates the headers from the body.

Message Body: Contains the JSON payload that represents the book details.

This is a basic example. In real-world scenarios, there might be additional headers like Authorization for authentication purposes or other complexities depending on the API's requirements.

HTTP Response Message Example:

Let's consider a scenario that is a continuation of the previous book example. Suppose the server processed the request to add a new book and now wants to return a confirmation to the client.

HTTP Response Example:

HTTP/1.1 201 Created
Date: Mon, 15 Aug 2023 12:30:00 GMT
Server: Apache/2.4.1 (Unix)
Content-Type: application/json
Content-Length: 150

{
  "id": 12345,
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald",
  "year": 1925,
  "genre": "Fiction",
  "message": "Book successfully added!"
}

Explanation:

Status Line:

• HTTP/1.1: The HTTP version.
• 201 Created: This is the status code and its associated message. A 201 status indicates that the request has been fulfilled, resulting in the creation of a new resource.

Headers:

• Date: The date and time at which the message was sent.
• Server: Information about the software used by the server to handle the request.
• Content-Type: Specifies the media type of the data being returned, in this case, application/json.
• Content-Length: Indicates the length of the response body.

Blank Line: This separates the headers from the body.

Message Body: Contains the JSON payload which, in this example, provides details of the added book along with a message confirming the successful addition.

Again, this is a simplistic example. Real-world scenarios might have additional headers or complexities based on what the API and application require.

HTTP Request and Response Payload XML Example

HTTP Request XML Payload Example

It is the responsibility of the consumer (client application) to prepare and send the HTTP request message as given below:

HTTP Request Example:

POST /SpringBootREST/customers HTTP/1.1
Accept: application/xml
Content-Type: application/xml
Content-Length: 196
User-Agent: Java/1.7.0_25
Host: 127.0.0.1:7000
Connection: keep-alive

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customer>
   <cid>0</cid>
   <cname>Ramesh</cname>
   <email>ramesh@gmail.com</email>
</customer>

From the above HTTP request, the payload is the body of the HTTP request message. It's optional and depends on the HTTP method name:

• In the case of the GET HTTP method, the HTTP request message is without a body.
• In the case of the POST HTTP method, the HTTP request message includes the body.

The Content-Type header in the above HTTP request message represents the payload format, which is XML. The Accept header in the HTTP request message represents the expected payload format in the HTTP response message, which is XML.

HTTP Response XML Payload Example

It is the responsibility of the business component (developed by the service provider) to prepare and send the HTTP response message as given below:

HTTP Response Example:

HTTP/1.1 200 OK
Content-Type: application/xml
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked
Date: Mon, 10 Nov 2019 09:45:34 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customer>
   <cid>1</cid>
   <cname>Ramesh</cname>
   <email>ramesh@gmail.com</email>
</customer>

The HTTP response message contains any one of the HTTP status codes ranging between 100 and 599:

• Informational: 1xx
• Successful: 2xx
• Redirection: 3xx
• Client-side error: 4xx
• Server-side error: 5xx

Read more about HTTP status codes at REST API - HTTP Status Codes

In the above response message, the payload means the body in the HTTP response message, and it is in XML format.

Conclusion 

Understanding payloads in REST APIs is essential for efficient data exchange between clients and servers. Whether you are sending or receiving data, knowing how to properly format and structure payloads according to the API's specifications ensures smooth communication and effective handling of data. By familiarizing yourself with different payload formats and their use in various HTTP methods, you can develop more robust and reliable RESTful APIs.

REST API Related Articles

• Overview of REST
• REST API - HTTP Methods
• REST API - HTTP Status Codes
• Advantages of REST
• REST API - REST Architectural Constraints
• REST API - REST Architectural Properties
• REST API - REST Architectural Elements
• Difference Between SOAP vs REST Web Services
• How to Identify REST Resources
• How to Design URL to REST Resource
• How to Assign HTTP Methods to REST Resources
• How to Model JSON Representation Format
• What HTTP Status Code to Return
• Restful API Design Best Practices
• Jersey Rest Hello World Example
• Jersey JAX-RS Restful CRUD Web Services Example
• Jersey Rest Developer Guide
• RESTEasy Hello World Example Tutorial
• RESTEasy JAX-RS Get, POST, PUT, and DELETE Tutorial
• RESTEasy Client for GET, POST, PUT, and DELETE RESTFul APIs