# The 7 layers of a predictable API

> From resource and method to the OpenAPI contract: seven consistency decisions that keep an API from surprising its clients, with examples from the source posts.

- Kind: Presentation
- Published: 2026-10-03
- Slides: 19
- Based on these articles: https://muhammetsafak.com/blog/fundamentals-of-restful-api-design/ · https://muhammetsafak.com/blog/pagination-filtering-and-sorting-in-rest-apis/ · https://muhammetsafak.com/blog/api-versioning-strategies-and-tradeoffs/ · https://muhammetsafak.com/blog/standardizing-api-responses-a-consistent-contract/ · https://muhammetsafak.com/blog/api-error-contract-returning-meaningful-errors-to-clients/ · https://muhammetsafak.com/blog/contract-first-api-design/
- Source: https://muhammetsafak.com/visuals/d/seven-layers-of-a-predictable-api/
- Language: en-US
- Author: Muhammet Şafak

---
## Slide 1 — The 7 layers of a predictable API

Muhammet Şafak — Visuals

An API that never surprises its client is the consistency of seven small decisions.

Muhammet Şafak October 3, 2026

## Slide 2 — Four stops

Flow

1.   Resource and status code Layers 1 and 2
2.   List endpoints Layer 3: pagination, filtering, sorting
3.   Response and error Layers 4 and 5
4.   Version and contract Layers 6 and 7

## Slide 3 — Every layer is a consistency decision

Seven layers

Resource

The URL is noun-based and plural; the HTTP method carries the action.

Status

Success is 2xx, client error is 4xx, server error is 5xx.

List

page, per\_page, sort, order: the same names on every endpoint.

Envelope

Every response has the same skeleton: success, data, message, errors.

Error

Errors come back as error.code, error.message, error.details.

Version

A breaking change calls for a new version.

OpenAPI

The contract is written before the code.

## Slide 4 — The method carries the action, not the URL

Layer 1 · Resource and method

The method carries the action, not the URL

| Method | Meaning | Example |
| --- | --- | --- |
| GET | Read | `GET /users/42` |
| POST | Create | `POST /users` |
| PUT | Replace entirely | `PUT /users/42` |
| PATCH | Update partially | `PATCH /users/42` |
| DELETE | Delete | `DELETE /users/42` |

## Slide 5 — The status code tells the outcome

Layer 2 · Status code

Returning 200 OK for every error and putting "error": true in the body works, but it goes against the REST principle.

| Class | Codes | Meaning |
| --- | --- | --- |
| 2xx | `200 · 201 · 204` | Succeeded; created; no content |
| 4xx | `400 · 401 · 403 · 404 · 422` | Bad data, identity, permission, not found, validation |
| 5xx | `500` | Unexpected error on the server side |

## Slide 6 — The identity of a page

Layer 3 · Pagination

-   2 current\_page last\_page: 15
-   20 per\_page Upper limit: min($adet, 100)
-   21–40 from – to Records on this page
-   287 total Total records

## Slide 7

Example from the source · OFFSET

Deeper pages, costlier OFFSET.

To reach page ten thousand, the database has to read through and skip 200,000 records; one solution is cursor pagination.

## Slide 8 — Every response has the same skeleton

Layer 4 · Response envelope

The client reads the same four fields on every endpoint: `success`, `data`, `message`, `errors`.

response.json

```
1{2"success": true,3"data": {},4"message": null,5"errors": null6}
```

## Slide 9 — Lists use the same envelope

Layer 4 · Response envelope

A paginated list comes back as `data.items` and `data.meta`; the envelope does not change.

response.json

```
1{2"success": true,3"data": {4  "items": [],5  "meta": {6    "current_page": 1,7    "per_page": 15,8    "total": 243,9    "last_page": 1710  }11},12"message": null,13"errors": null14}
```

## Slide 10 — An error is a contract too

Layer 5 · Error contract

`code` is fixed for machines, `message` can change for humans, `details` carries extra context.

error.json

```
1{2"error": {3  "code": "VALIDATION_FAILED",4  "message": "Gönderilen veriler doğrulanamadı.",5  "details": [6    {7      "field": "email",8      "message": "Geçerli bir e-posta adresi giriniz."9    },10    {11      "field": "phone",12      "message": "Telefon numarası zorunludur."13    }14  ]15}16}
```

## Slide 11 — Envelope and error rules

Layers 4 and 5

-   **Error with 200** Returning 200 + "error": true for errors works but goes against REST; caching and logging break.
-   **Format** Error codes in uppercase with underscores: QUOTA\_EXCEEDED.
-   **Codes** New codes can be added, old codes should not be removed.
-   **Scale** In a small service with a single client, a status code and a short message are enough.

## Slide 12 — Three strategies, URI preferred

Layer 6 · Versioning

The preferred one is URI versioning: readability, separate documentation, separate route groups.

| Strategy | Example | Trade-off |
| --- | --- | --- |
| URI | `GET /api/v1/users` | Clearly visible in logs and proxies; multiplies URLs |
| Header | `X-API-Version: 2` | URLs stay clean; a missing header creates ambiguity |
| Query | `GET /api/users?version=2` | Practical at the start; proxies and CDNs may not see it |

## Slide 13 — At a basic level: which change calls for a new version?

Layer 6 · Versioning

#### Compatible

-   Adding a new field to the response.
-   Adding an optional parameter.
-   Enriching error messages.

#### Breaking

-   Removing or renaming an existing field.
-   Adding a required parameter.
-   Changing the response structure or the status code.

## Slide 14

Deprecation

Give at least 6–12 months' notice.

For an API open to external clients, a deprecation period of at least 6-12 months is reasonable.

## Slide 15 — Announce a version's lifespan with a header

Layer 6 · RFC 8594 (2019) · RFC 9745 (2025)

RFC 8594: May 2019, Informational. RFC 9745: March 2025.

| Header | Document | What it says |
| --- | --- | --- |
| `Deprecation: @1780272000` | RFC 9745 | When it was deprecated; the value is a date, true is invalid |
| `Sunset: Sat, 31 Oct 2026 23:59:59 GMT` | RFC 8594 | When it will stop responding |
| `Link: <…/docs/migrate-v2>; rel="deprecation"` | RFC 9745 | The address of the migration guide |

## Slide 16 — Contract first, code later

Layer 7 · Contract-first

1.   Step 1: Contract `OpenAPI 3.0.3`
2.   Step 2: Parallel work `backend · UI · test`
3.   Step 3: Mock `Prism`
4.   Step 4: Validation `contract testing`
5.   Step 5: Update `contract or code`

## Slide 17 — The contract is written before the code

Layer 7 · OpenAPI

The schema excerpt of the example contract. The `/orders` endpoint restricts the `status` filter to `pending`, `completed`, `cancelled`.

openapi.yaml

```
1components:2schemas:3  Order:4    type: object5    required: [id, status, total]6    properties:7      id:8        type: integer9      status:10        type: string11      total:12        type: number
```

## Slide 18 — When does contract-first pay off?

Layer 7

-   **Small project** One developer, small project: contract-first can be overkill.
-   **Many consumers** Web, mobile, third parties: it definitely saves time.
-   **Long life** In an API that will live for years, the contract is a decision record.

## Slide 19 — Thank you

[muhammetsafak.com](https://muhammetsafak.com)

Seven layers, seven promises of consistency. The details are in the six source posts.
