REST API Design Best Practices

What this best practices guide is

A language-agnostic guide to REST API design for developers who build HTTP APIs that other teams, apps or customers depend on. It covers resource and URL design, HTTP method semantics, status codes, RFC 9457 error responses, payload conventions, pagination and filtering, idempotency and concurrency control, and versioning, deprecation and documentation with OpenAPI.

It has 8 chapters and 31 practices, each with why it matters, what to do and what to avoid. For backend developers who design APIs.

Chapter by chapter

1. Resources and URLs (4 practices)

How to model an API as resources and name their URLs so they stay predictable as the API grows.

2. HTTP methods and their promises (4 practices)

What GET, POST, PUT, PATCH, DELETE and the new QUERY method promise to clients and intermediaries, and how to keep those promises.

3. Status codes (4 practices)

Choosing status codes that let clients react correctly without parsing the body, and the headers some codes require.

4. Error responses (4 practices)

Returning errors in one standard, machine-readable format that clients can handle without special cases.

5. Request and response bodies (4 practices)

Conventions for JSON payloads that keep an API consistent, unambiguous and easy to extend.

6. Pagination, filtering and sorting (4 practices)

How to return large collections in pages that stay fast and correct, and how to let clients filter and sort safely.

7. Idempotency, concurrency and caching (3 practices)

Making retries safe, stopping clients from overwriting each other and letting caches do their job.

8. Versioning, deprecation and documentation (4 practices)

How to change an API without breaking the people who depend on it, and how to describe it so they can use it without asking you.

How it works on Sefism

The guide reads like a short course: a syllabus, then one chapter per page in a focused reader, with a quiz at the end of each chapter for members. The opening chapters are open to everyone. Adding it to your account uses credits, opens every chapter and keeps your progress.

Every claim is checked against the sources listed on the page (8 cited).