# Consistent Shapes — REST API Design

Source: https://www.geekswithgeeks.com/en/restapi/api-request-response-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.

```json
{
  "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.