What is the payload in an API interaction?

When a client and a server communicate via API, the first sends a request to the second, which processes the request and returns a payload containing the result of the operation, which can concern creating a new user as much as extracting information from a database.

The payload, or “useful load” of the interaction, is that part of the communication that contains the data to be transmitted, for example the username and email address to be associated with a new account or the summary of the operation carried out.

Payload: what it is and what it contains

In data transmission, the payload is the portion of the message that contains the data to be transmitted, literally the “useful load” of the information exchange between client and server.

When a client sends a request, it transmits a data packet that includes several instructions necessary to make the communication protocol work, such as metadata and headers, which carry information like the content type or any error messages. The payload is inside the same packet and is what contains the actual data to be transmitted.

In a request, for example, the payload can contain the data of a user logging in or the query in an API call, while in a response it can contain the result of the operation or the requested data.

The content of the payload essentially depends on the context: in payment processing it can include credentials, payment details, and metadata related to the transaction; on social networks it can transmit multimedia files; in booking systems it can carry information such as availability and prices.

The Payload in API calls: some examples

The payload, therefore, is the message that is actually transmitted between client and server. It can be an image, a PDF, or a list of names. In interactions that involve the transmission of metadata, it is almost always an object in Json or XML format, whose content can vary greatly depending on the type of operation.

For example, if we are creating a new user, the request payload must contain the data necessary for creating the new account (e.g.: {"username": "newuser", "email": "[email protected]", "firstName": "Mario", "lastName": "Rossi"}), while the response will include information such as the new user’s ID, their data, and a message like “Account successfully created” (e.g.: {"id": "123", "username": "newuser", "email": "[email protected]", "message": "Account successfully created"}).

If we are instead retrieving information from a database, the request payload will coincide with the specific query (for example, {"query": {vatCode_or_taxCode_or_id}}), while the response will contain the requested data, in our case {"taxCode": "12485671007", "companyName": "OPENAPI SPA", "vatCode": "12485671007"}.

The payload in Rest API: HTTP methods

In Rest API calls, the content of the payload also depends greatly on the HTTP method used, which defines the action to be performed on the requested resource:

• GET: is the method used to read data from a server, for example to extract data from a database. In GET requests, the payload contains the requested data (see example above). It is used only in the response, as the data needed for the request is generally already included in the request string or object;

• POST: if creating a new resource on the server, for example inserting a new product in an e-commerce, the request payload must contain the data necessary to create the new resource, and will be a Json like {"name": "Product Name", "price": 123, "description": "Product description.", "category": "Product category"}. The response will contain the outcome of the request, i.e., the success status and details of the creation of the new product, for example the resource ID and creation date;

• PUT: when updating resources, the payload must contain a complete representation of the resource to be updated, including the new values to be set. In updating e-commerce products, for example, the PUT request payload will contain information like {"id": "123", "name": "New Product Name", "price": "New price", "available": true}. The response payload generally contains a success status and a message like “product successfully updated”;

• DELETE: a DELETE request does not require a payload but may include information like the ID of the resource to be deleted or other details. The response almost always contains only the success status and possibly some details about the operation;

• PATCH: in PATCH requests, the payload contains only the data to be modified. For example, if we want to update the email field of the user with ID 123, the payload sent to the endpoint identifying the user will contain only the new email address, while the response can return the modified elements or the entire updated resource, along with the success status.

The payload in interactions with Openapi

The payloads transmitted in an API interaction, especially response payloads, contain much more than just the requested data. They include essential information for managing the interaction by the client, such as success status (for example, “success”: true) and any textual messages (for example, “message”: “invalid password”).

Openapi API payloads adopt the Json standard. In API requests, they contain request information, for example sender, recipient, and content of an SMS.

In Openapi API responses, the payloads contain 4 fields:

• Data: the data transmitted. In a request for sending a registered mail via API, for example, the “data” section includes all necessary information for sending, such as sender information, recipient name and address, the message to send, and printing options. In the response, the same data will be present, along with the document URL and payment details;
• Success: indicates success status, can be "success": true or "success": false;
• Error: communicates any error messages;
• Message: is the section of the payload that includes messages intended for end users, often sent in case of an error or missing data in the request, for example "invalid query" or "specify the payment type".

The payload, as we have seen, is the fundamental contract between client and server, the element that defines the intent (request) and the result (response) of the interaction. Therefore, its structure can greatly influence the efficiency and scalability of an API architecture. A strict and consistent payload structure is essential to ensure interoperability and ease of integration, as well as to guarantee efficient and easily maintainable processes.