In this short article, we will learn what is payload in REST API.
What is Payload in REST API?
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:
- 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.
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.
- 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.
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:
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:
- 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.
- 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.
HTTP Request and Response Payload XML Example
HTTP Request XML Payload 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 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 CodesFrom the above Response message, the payload means the body in the HTTP response message and the payload is in XML format.
REST API Related Articles
- Overview of REST
- REST API - HTTP Methods // Popular
- REST API - HTTP Status Codes // Popular
- Advantages of REST
- REST API - REST Architectural Constraints // Popular
- 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 // Popular
- How to Assign HTTP Methods to REST Resources
- How to Model JSON Representation Format // Popular
- What HTTP Status Code to Return
- Restful API Design Best Practices // Popular
- Jersey Rest Hello World Example
- Jersey JAX-RS Restful CRUD Web Services Example // Popular
- Jersey Rest Developer Guide
- RESTEasy Hello World Example Tutorial // Popular
- RESTEasy JAX-RS Get, POST, PUT, and DELETE Tutorial // Popular
- RESTEasy Client for GET, POST, PUT, and DELETE RESTFul APIs
Comments
Post a Comment
Leave Comment