What is a payload in API?
APIs have proven to be some of the best tools and protocols for permitting interaction, communication, and sharing of data between various applications and web services. And while understanding how the interaction and communication occur may be an uphill task, the other daunting task is to familiarize yourself with the endless list of terms associated with APIs.
While you may think that you understand everything about APIs, you’ll always come to discover that there is a new term that you didn’t know it existed. For instance, if you deal with API, you might have stumbled upon the term Payload being used on several occasions. But the bugging question is, do you what it is all about? In this article, we’ll try to uncover the meaning of the term payload and provide a few examples to help you understand what it entails.
What is a Payload?
In computer programming, various apps and systems share data and information regularly over the internet. When each unit of data is transmitted, it boasts two essential parts: the header/overhead identifier and the actual information dubbed payload.
The overhead/ header data is used as an identifier, and its sole purpose is to indicate the source and destination of the information being transmitted. This section of the data is striped off once the message reaches its destination. On the other hand, the payload refers to an integral part of each unit of data being transmitted. It is part of the unit data that carries the real message that an app or system needs for it to act.
Simply put, the term payload is utilized by programmers to differentiate between the essential information in a chunk of data and the information that is used to support it. The term originated from the transportation sector, where it refers to the load that a person pays for when they transport something.
Let’s, for example, consider a truck is carrying 15 tons of cement. When it passes through the weighbridge, it weighs more than 15 tons, taking into account the vehicle’s weight, the driver, and all the other things. However, although it transports all these things, the only item that the customer pays for is cement, hence the payload.
A payload in API is the actual data pack that is sent with the GET method in HTTP. It is the crucial information that you submit to the server when you are making an API request. The payload can be sent or received in various formats, including JSON. Usually, the payload is denoted using the “{}” in a query string.
Payload = “{}”
Example of Payloads
In programming and software development, the payload is used in the context of message protocol to differentiate between the assisting and actual data in a query string. For instance, Let’s consider this JSON web service response.
{
"status":"OK",
"data":
{
"message": "Welcome, world!"
}
}
In the above example, the payload is the Welcome, World! Since it is the part of the query string that the user is interested in. The rest of the information is referred to as the overhead data. This is because it is only used to show the source or destination and display authenticity.
API Payload Formats
Basically, you’ll find three payload formats:
- Request payload format
- OK response payload format
- FAILED response payload format
API Request Payload Format
This request must have two parameters and a subelement:
- Interface Type
- Method name
- Parameters
Example:
{
"interfaceType": "Manual",
"methodName": "",
"parameters": {
}
}
API OK Response Payload Format
These features one parameter and one subelement:
- Response type
- Data. It may be zero or more parameters
Example:
{
"responseType": "OK",
"data": {
"someName1": "value",
"someName2": "value",
"someName3": "value"
}
}
API FAILED Response Payload Format
This also contains one parameter and one subelement:
- Response type
- Messages. May feature an array of zero or multiple error messages
Example:
{
"responseType": "FAILED",
"messages": [
{
"message": ""
},
{
"message": ""
},
{
"message": ""
}
]
}
Conclusion
If you didn’t know what a payload is, this article has provided you with an in-depth understanding of what it’s and how important it’s to the API world. Generally, the payload is the part of a query string that carries the essential message or information required by the server to generate a response or the user to make a decision.
