In this short article, we will learn what is payload in REST API.

What is Payload in REST API?

In a REST API, a payload refers to the data or information that is sent by the client in a request to the server or the data that is returned by the server in response to a request. The payload typically contains the 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. It is important to ensure that the payload is properly formatted and structured according to the API's specifications to ensure proper communication and handling of data.

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 name in the HTTP request message is used to represent the payload format in the HTTP request message. For example JSON, XML, etc.

The 'Accept' header name in an HTTP request message is used to represent the expected payload format in an HTTP response message. Examples: 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, which includes the HTTP method, the request URI, and the HTTP version.
Headers that provide meta-information about the request.
A blank line indicating the end of the headers.
The message body, which contains the JSON payload.

Let's take a look at an example. Imagine you are developing a RESTful API for managing a collection of books, and you want to add a new book to your collection.

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 in 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 Message 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 means client application to prepare and send HTTP request message as given below:

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 means the body in the HTTP request message. It's optional and depends on the HTTP method name i.e.,

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 with the body

The 'Content-Type' header name in the above HTTP request message is used to represent the payload format in the HTTP request message and the payload format is XML.

The 'Accept' header name in an HTTP request message is used to represent the expected payload format in an HTTP response message and the payload format is XML.

Http Response XML Payload Example

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

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

From the above Response message, the payload means the body in the HTTP response message and the payload is in XML format.

Java Guides

Search This Blog