API Design: Representations

Data representations like JSON and XML act as the “language” APIs use to structure and format the information being exchanged. A data representation provides a standardized way to structure data, making it understandable for both the sender (API server) and the receiver (client application).

Common representations include:

• JSON
• XML
• Protobufs
• YAML

JSON (JavaScript Object Notation)

JSON is the most common data representation used today since it integrates seamlessly with JavaScript, is human-readable (and thus is easier to debug), and is simple to use.

It’s structured with key-value pairs, nested objects, and arrays for flexible modeling of data relationships.

Example:

{
  "product_id": 12345,
  "name": "Widget X",
  "price": 9.99
} 

XML (Extensible Markup Language)

XML is used less in today’s world, but offers a highly customizable way of structuring data using tags and attributes. It’s popular for legacy systems or scenarios requiring granular data definitions.

It’s structured as a hierarchical model with nested elements.

Example:

<product>
  <product_id>12345</product_id>
  <name>Widget X</name>
  <price>9.99</price>
</product>

Protocol Buffers (Protobufs)

Protobufs are a binary format designed by Google that is known for its efficiency and speed. It’s used in microservices and large scale systems, where the “weight” of JSON starts increasing bandwidth compared to using Protobufs, which can be over half the size of the equivalent JSON representation.

It comes with robust APIs and is great for environments where multiple programming languages are used.

Example:

syntax = "proto3";

message ChatMessage {
    string sender_id = 1;
    string content = 2;
    int64 timestamp = 3;
}

YAML (Yet Another Markup Language)

YAML prioritizes human readability above all, so it’s mostly used for config files. In APIs, it’s not used often.

Example:

product:
    id: 12345
    name: Widget X
    description: "The ultimate widget for all your widgeting needs."
    price: 9.99
    categories: 
      - gadgets
      - tools

Comparing Data Representations