Dec 28, 2024 API

What response formats are supported in REST APIs?

Photo by Alicia Christin Gerald / Unsplash

Before discussing the various formats supported by REST APIs, it's important to note that JSON (JavaScript Object Notation) has become the de facto industry standard for most modern web APIs. JSON is often chosen as the primary data format due to its simplicity, readability, and widespread support across programming languages and platforms.

However, this blog post aims to provide a comprehensive overview of "what's out there" in terms of REST API response formats. While JSON dominates the landscape, understanding alternative formats can be valuable for specific use cases, legacy systems, or specialized industries.

REST (Representational State Transfer) is not tied to any specific data format as it's an architectural style rather than a protocol. REST APIs can, therefore, support a wide range of data formats. Here's a list of the most common formats supported by REST APIs (in no particular order):

JSON (JavaScript Object Notation)
XML (Extensible Markup Language)
YAML (YAML Ain't Markup Language)
Plain Text
HTML (HyperText Markup Language)
JSON Lines (JSONL)
CSV (Comma-Separated Values)
Protocol Buffers (Protobuf)
Avro
MessagePack
Form-Encoded (application/x-www-form-urlencoded)
Binary Files
GraphQL Responses

Each format has its own strengths and use cases, which we'll explore in detail throughout this post. By understanding the variety of formats available, API designers and consumers can make informed decisions based on their specific requirements, even if JSON remains the most common choice for the majority of modern REST APIs.

1. JSON (JavaScript Object Notation)

Description: A lightweight, text-based format that's easy to read and write for both humans and machines.
Usage: The most popular format for REST APIs, especially in web and mobile applications.
MIME type: application/json
Example:

{
    "user": {
        "id": 1,
        "name": "Arvid Berndtsson",
        "email": "[email protected]",
        "status": "active"
    }
}

2. XML (Extensible Markup Language)

Description: A more structured and formal format than JSON, often used in older systems or when strict validation is needed.
Usage: Common in enterprise applications and systems that require high interoperability.
MIME type: application/xml or text/xml
Example:

<user>
    <id>1</id>
    <name>Arvid Berndtsson</name>
    <email>[email protected]</email>
    <status>active</status>
</user>

3. YAML (YAML Ain't Markup Language)

Description: A human-readable format that's easier to understand than XML and JSON.
Usage: Sometimes used for API configurations or when data needs to be easily read by humans.
MIME type: application/x-yaml
Example:

user:   
    id: 1
    name: Arvid Berndtsson
    email: [email protected]
    status: active

4. Plain Text

Description: Simple text format, common for simple API responses or error messages.
Usage: Good for minimalist applications or debug information.
MIME type: text/plain
Example:

User Arvid Berndtsson (ID: 1) is active.

5. HTML (HyperText Markup Language)

Description: Format for sending web pages as responses from REST APIs.
Usage: Used when REST APIs deliver web-based content.
MIME type: text/html
Example:

<html>
    <body>
        <h1>User Profile</h1>
        <p>Name: Arvid Berndtsson</p>
        <p>Email: [email protected]</p>
        <p>Status: Active</p>
    </body>
</html>

6. JSON Lines (JSONL)

Description: A format where each line is a separate JSON object, particularly useful for data streams.
Usage: Efficient for logging and streaming data.
MIME type: application/jsonlines or application/x-ndjson
Example:

{"id": 1, "name": "Arvid Berndtsson", "email": "[email protected]"}
{"id": 2, "name": "Simon Berndtsson", "email": "[email protected]"}

7. CSV (Comma-Separated Values)

Description: A table format used to transfer data in row and column structure.
Usage: Common for data export or integration with spreadsheet programs.
MIME type: text/csv
Example:

id,name,email,status
1,Arvid Berndtsson,[email protected],active
2,Simon Berndtsson,[email protected],inactive

8. Protocol Buffers (Protobuf)

Description: A binary format developed by Google that is very compact and fast to transfer and process.
Usage: Used in high-performance applications or where network bandwidth is limited.
MIME type: application/x-protobuf
Example: (Binary data, not human-readable)

9. Avro

Description: A binary serialization format often used with Apache Kafka for streaming data.
Usage: Supports high-performance APIs and distributed systems.
MIME type: application/avro
Example: (Binary data, not human-readable)

10. MessagePack

Description: A binary JSON format that is compact and faster than text-based JSON.
Usage: Good for applications with limited network bandwidth.
MIME type: application/x-msgpack
Example: (Binary data, not human-readable)

11. Form-Encoded (application/x-www-form-urlencoded)

Description: Often used to send simple form data in POST requests.
Usage: Common in API calls from web forms.
MIME type: application/x-www-form-urlencoded
Example:

name=Arvid+Berndtsson&email=arvid%40example.com&status=active

12. Binary Files

Description: REST APIs can transfer binary files such as images, videos, or PDF documents.
Usage: Suitable for file downloads or uploads.
MIME type: Depends on the file type, e.g., image/png, application/pdf.
Example: (Binary data, not human-readable)

13. GraphQL Responses

Description: Although GraphQL is not part of REST, REST APIs can be designed to support GraphQL queries and send JSON responses.
Usage: Hybrid API strategies.
MIME type: application/json
Example:

{
  "data": {
    "user": {
      "name": "Arvid Berndtsson",
      "email": "[email protected]"
    }
  }
}

REST API Response Formats - Pros and Cons

Format	Pros	Cons
JSON (JavaScript Object Notation)	+ Human-readable + Widely supported + Lightweight + Easy to parse in most languages	- No built-in schema validation - Can be verbose for simple data - Limited data types
XML (Extensible Markup Language)	+ Supports complex structures + Built-in schema validation + Widely used in enterprise systems	- Verbose - More complex to parse - Larger payload size
YAML	+ Very human-readable + Good for configuration + Supports complex structures	- Not as widely supported as JSON/XML - Sensitive to indentation - Parsing can be slower
Plain Text	+ Simplest format + No parsing required + Human-readable	- No structure - Limited to string data - Difficult to represent complex data
HTML	+ Directly renderable in browsers + Familiar to web developers	- Not suitable for pure data transfer - Mixing of content and structure
JSON Lines (JSONL)	+ Good for streaming data + Each line is valid JSON	- Not a single valid JSON document - Less support than standard JSON
CSV	+ Easy to open in spreadsheets + Simple for tabular data	- Limited to flat data structures - Issues with commas in data
Protocol Buffers	+ Very efficient serialization + Small payload size	- Not human-readable - Requires schema definition
Avro	+ Supports schema evolution + Compact binary format	- Not human-readable - Less widespread than Protobuf
MessagePack	+ Compact binary format + Faster than JSON	- Not human-readable - Less support than JSON
Form-Encoded	+ Simple to generate + Works well with HTML forms	- Limited to simple key-value pairs - Not suitable for complex data
Binary Files	+ Efficient for non-text data + Preserves file integrity	- Not human-readable - Requires specific handling
GraphQL Responses	+ Flexible data querying + Reduces over-fetching	- More complex to implement - Learning curve for clients

Conclusion

The choice of format for a REST API depends on various factors, including the nature of the data, client needs, performance requirements, and the ecosystem in which the API operates. While each format has its strengths and ideal use cases, JSON has become the de facto standard for many modern web APIs due to its simplicity and widespread support.

Readability: How important is the human readability of the raw data?
Parsing Efficiency: How quickly can clients process the data?
Size and Bandwidth: How much data needs to be transferred?
Schema Support: Do you need strict data validation?
Ecosystem Compatibility: What formats are best supported by your tech stack?
Client Requirements: What formats can your API consumers easily work with?

Understanding these different formats and their appropriate use cases can help you make informed decisions that best serve your API's purpose and its consumers. Many modern APIs support multiple formats through content negotiation, allowing clients to request their preferred format and thus increasing the API's flexibility and usability.

That said, let's be real—unless you have some really specific needs, you can save yourself the headache by going with JSON.

Subscribe to my newsletter

No spam, no sharing to third party. Only you and me.