Lesson 8 / 24

Consistent Shapes

Designing predictable envelopes for requests and responses.

Same shape every time

A resource should look the same whether it's returned alone or inside a list. Don't rename fields or nest differently between GET /orders/482 and an item inside GET /orders.

A collection envelope

Wrapping a list with metadata keeps room to grow without breaking clients.

{
  "data": [
    { "id": 482, "status": "shipped" },
    { "id": 483, "status": "pending" }
  ],
  "meta": {
    "total": 214,
    "page": 1
  }
}

Never return a bare array

A top-level JSON array response can't add metadata later without breaking every client, and is a historical CSRF risk. Wrap it in an object with a data key from day one.