What is Payload? A Quick Guide [+ Examples]

As humans, we communicate with others in various ways. We have verbal conversations face to face, written communication through text messaging or letters, and nonverbal communication with our body language. With any communication channel, a message is transmitted from the sender to the recipient and vice versa. Similar to human communication, computer networks need a way to pass on data from a sender to a receiver.

In this article, we will study how data is transmitted over the internet, focusing on payloads within an API. First, we will clearly define the relationship between an overhead and a payload. Then, we will explore the different communication formats used within a payload in API. Let's begin.    

What is a payload in API?

Technology is moving faster than ever before. In fact, new technologies are released on a daily basis. For instance, one of the world’s fastest aircraft is NASA's X3 jet plane, with a top speed of 7,000 mph.

We have definitely come a long way from traveling by horse and wagon. Today, it's hard to imagine a world without computer networks operating behind the scenes. But have you ever wondered, just how information is passed from one network to the other? A way that we pass this information is through payload within an API. Payload is the data you send over the computer network. Let's explore this question further.

Payload in API Overview

When data is sent over the internet, it spits out two pieces of information: overhead and payload. The overhead data is the identifier used to show the source or destination of the payload. Since it is only used in the transmission process, the overhead information is removed from the view once it reaches its destination.  

For a better understanding, imagine sending the message, "Hello" and labeling it "msg" (short for message). "Hello" is referred to as the payload and "msg" is the overhead. Once the overhead and payload reach their destination, the only data that is viewable is "Hello". The label "msg" is only used for internal purposes to identify your data.  

The payload of an API can be sent or received in various formats such as JSON or XML. In a query string, the payload can usually be identified using curly braces "{}".

Payload in API Example  

Payload is the essential information in the data block that you send or receive from the server. Below we included an example of a JSON payload within an API.

 POST /echo/post/json HTTP/1.1
Host: hubspot.com
Accept: application/json
Content-Type: application/json
Content-Length: 25

{
   "cid": 1,
   "cname": "Hubspot",
}

In the example, the payload data is the "1" and "Hubspot". The remaining information is the header/overhead data.

Next, consider this XML payload example.

 <company>
   <cid>1</cid>
   <cname>Hubspot</cname>
</company>

Though the format is slightly different, the payload and overhead data remain the same.

Payload Formats

There are three types of payload formats we will discuss:

• API Request payload format
• API OK response payload format
• API Failed response payload format  

1. API Request Payload Format

A payload API request requires two parameters and one subelement:

• interfaceType: The interfaceType identifies that this is an API request format. It must be set to "Manual".
• methodName: The methodName defines the API method to call.
• parameters: The parameters are required by the method being called.
  

   {
     "interfaceType": "Manual",
     "methodName": "",
     "parameters": {
     }
  }

2. API OK Response Payload Format

A successful payload response will contain one parameter and one subelement:

• responseType: The responseType must be set to "OK".
• data: The data may contain zero or more parameters required for the called method's response.
  

   {
     "responseType": "OK",
     "data": {
     "companyName1": "value",
     "companyName2": "value",
     "companyName3": "value"
     }
  }

3. API Failed Response Payload Format

A failed payload response will contain one parameter and one subelement:

• responseType: The responseType must be set to "FAILED".
• messages: The messages may contain an array of zero or more error messages.

 {
   "responseType": "FAILED",
   "messages": [
     {
        "message": ""
     },
     {
        "message": ""
     },
     {
        "message": ""
     }
   ]
}

Communicating With Payload in an API  

In computer networks, communication consists of sending and receiving messages. The sender must correctly address the message while the receiver must have all the required resources to process the message.

We have determined that payload in an API is used in the context of a message to distinguish it from the overhead data. The overhead data is required to correctly interpret the request. With this information, you now have a better understanding of how messages are transmitted in computer networks using a payload in an API.