What type of payload is REST API?

REST (Representational State Transfer) API is a software architectural style that defines a set of constraints for creating web services. REST APIs use various formats to send and receive data, known as payloads. The payload contains the data being transferred in the request or response. Some common payload formats used by REST APIs include:

Table of Contents

JSON

JSON (JavaScript Object Notation) is a lightweight data interchange format that is easy for humans to read and parse. JSON is language-independent and very popular for web APIs and mobile applications. JSON payloads contain attribute-value pairs and array data types. For example:

{
  "name": "John Doe",
  "age": 35,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA"
  },
  "hobbies": ["reading", "hiking", "swimming"]
}

Benefits of using JSON payloads:

Compact data format
Fast to parse and generate

Supported natively in JavaScript
Human-readable structure

XML

XML (Extensible Markup Language) is another widely used format for REST API payloads. XML provides a standardized way to annotate and structure data. XML payloads contain hierarchical data wrapped in opening and closing tags. For example:

<person>
  <name>John Doe</name>
  <age>35</age>
  <address>
    <street>123 Main St</street>
    <city>Anytown</city>
    <state>CA</state>
  </address>
  <hobbies>
    <hobby>reading</hobby>
    <hobby>hiking</hobby>
    <hobby>swimming</hobby>
  </hobbies>
</person>

Benefits of XML payloads:

Structured data format
Self-descriptive with custom tags

Wide language support
Capable of data validation

Plain Text

Plain text is the simplest format for REST API payloads. It consists of alphanumeric characters without any markup or structure. Plain text payloads are easy to read and don’t require any parsing. For example:

John Doe
Age: 35
Address: 123 Main St, Anytown, CA
Hobbies: reading, hiking, swimming

Benefits of plain text payloads:

Human-readable
No parsing required

Lightweight
Supports all text encodings

HTML

HTML (HyperText Markup Language) can also be used as a payload format in REST APIs, especially when the response contains rich text or needs to be rendered by a browser. HTML markup allows for text styling, hyperlinks, images, and other visual formatting. For example:

<html>
<body>

<h1>John Doe</h1>

<p>Age: 35</p>

<p>Address: 123 Main St, Anytown, CA</p>

<p>Hobbies:</p>
<ul>
  <li>reading</li>
  <li>hiking</li>
  <li>swimming</li>
</ul>

</body>
</html>

Benefits of HTML payloads:

Rendered easily by web browsers
Familiar and human-readable

Supports styling, layouts, and media
Readable across different platforms

Form Data

Form data is used to submit data like web form field values and uploaded files. It uses a content type of application/x-www-form-urlencoded or multipart/form-data. The key-value pairs are encoded for transmission over HTTP. For example:

name=John+Doe&age=35&address=123+Main+St%2C+Anytown%2C+CA

--boundary
Content-Disposition: form-data; name="name"

John Doe
--boundary
Content-Disposition: form-data; name="age" 

35
--boundary
Content-Disposition: form-data; name="address"

123 Main St, Anytown, CA
--boundary--

Benefits of form data payloads:

Allows submission of web form data

Supports file uploads
Common standard format
Supported by all major frameworks

Binary Data

Binary data payloads contain compressed or encoded data like images, audio, video, and other multimedia content. The binary data is usually transmitted opaquely as a stream of bytes. Some common binary types used by REST APIs include:

Image Files (JPG, PNG, GIF)
Audio Files (MP3, WAV, AIFF)

Video Files (MP4, AVI, MOV)
Compressed Files (ZIP, RAR)

Benefits of binary data payloads:

Allows transfer of multimedia content
Compact data representation
No parsing required

Supported by all frameworks and languages

Protocol Buffers

Protocol buffers are a binary serialization format developed by Google for serializing structured data. It results in smaller and faster messages that can be parsed very efficiently. The data is defined in .proto schema files then compiled for each target language to generate classes for serialization. For example:

message Person {
  required string name = 1;
  required int32 age = 2;
  required string address = 3;
  repeated string hobbies = 4;
}

Benefits of protocol buffers:

Compact, efficient, fast to parse
Language-neutral, platform-neutral
Supports schema evolution

Additional serialization formats supported

Other Formats

Some other payload formats occasionally used by REST APIs include:

CSV – For tabular data exchange

AMF – Action Message Format binary format
MsgPack – Efficient binary serialization format
Thrift – Compact binary data format

Avro – Binary data serialization system

Conclusion

In summary, the most common payload formats used by REST APIs are JSON, XML, plain text, HTML, and form data. JSON is the predominant format for web APIs today due to its lightweight structure, wide support, and human readability. Other binary formats like protocol buffers can also be used for efficiency in mobile apps and internal communications. The payload format can be selected based on the use case, required structure, platform support, bandwidth, and processing requirements.

Payload Format	Benefits	Drawbacks
JSON	Lightweight, human-readable, widely supported	Less structured than XML
XML	Self-descriptive, extensible, capable of validation	More verbose than JSON
Plain Text	Simple, human-readable, lightweight	Limited structure and metadata
HTML	Readable across platforms, supports styling	More overhead than plaintext
Form Data	Allows web form and file submission	Less structure than JSON or XML
Binary Data	Efficient for multimedia content	Not human-readable
Protocol Buffers	Compact, efficient, fast to parse	Requires compilation step