What is Payload? A Quick Guide [+ Examples]

Download Now: How to Use an API
Danielle Richardson Ellis
Danielle Richardson Ellis

Published:

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.

woman explores what a payload is on a laptop

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.

Download Now: How to Use an API [Free Ebook]

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.

Table of Contents

What is a payload in an API?

In the context of an API (Application Programming Interface), a payload refers to the data that is sent in a request or received in a response. It is the essential content of the message being transmitted between a client (such as a web application or mobile app) and a server. The payload contains the information necessary to perform a specific operation or retrieve specific data.

For instance, when making an HTTP request to a server using an API, the payload is typically included in the body of the request. The payload is usually formatted in a structured way, such as JSON (JavaScript Object Notation) or XML (eXtensible Markup Language), depending on the API’s design and specifications.

Payload in API Overview

payload api, JSON example

Image Source

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 Examples

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.

1. X API

Overview: The X (Twitter) API allows developers to access and interact with X’s vast dataset, enabling them to build applications that can read, write, and manage tweets, user accounts, and various X functionalities.

Endpoints: The API provides endpoints for actions like fetching user timelines, posting tweets, searching for tweets, retrieving user information, and more.

Payload Example (POST Request for Tweeting):

Endpoint: POST /statuses/update Payload: { "status": "Hello, Twitter! This is a test tweet from my API client. #API #Twitter" }

2. Google Maps API:

Overview: The Google Maps API allows developers to integrate Google Maps into their applications and websites, offering functionalities like displaying maps, creating custom markers, calculating directions, and geocoding.

Endpoints: The API provides endpoints to interact with map data, places, and directions, among others.

Payload Example (GET Request for Geocoding):

Endpoint: GET /maps/api/geocode/json

Query Parameters: { "address": "1600 Amphitheatre Parkway, Mountain View, CA" }

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.
{ "name": "John Doe", "email": "john.doe@example.com", "age": 30, "is_active": true, "interests": ["programming", "reading", "hiking"] }

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.
{ "user_id": 12345, "name": "John Doe", "email": "john.doe@example.com", "age": 30, "is_active": true, "interests": ["programming", "reading", "hiking"], "created_at": "2023-07-21T12:34:56Z" }

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.
{ "error_code": 404, "error_message": "User not found", "error_details": { "request_id": "123abc", "timestamp": "2023-07-21T15:45:32Z" }

The API request payload format depends on the API’s design and the data required for the specific action. However, two common data interchange formats used in API request payloads are JSON and XML. Both formats are widely supported and provide a structured way to represent data.

JSON (JavaScript Object Notation):

JSON is a lightweight and human-readable data interchange format that is easy for both humans and machines to understand. It is widely used in modern web development and APIs. JSON payloads consist of key-value pairs and can represent various data types, such as objects, arrays, strings, numbers, booleans, and null.

Example JSON payload for creating a user in a hypothetical API:

{ "name": "John Doe", "email": "john.doe@example.com", "age": 30, "is_active": true, "interests": ["programming", "reading", "hiking"] }

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.

api

Related Articles

We're committed to your privacy. HubSpot uses the information you provide to us to contact you about our relevant content, products, and services. You may unsubscribe from these communications at any time. For more information, check out our Privacy Policy.

Everything you need to know about the history and use of APIs.

CMS Hub is flexible for marketers, powerful for developers, and gives customers a personalized, secure experience

START FREE OR GET A DEMO