> ## Content Index
> Fetch the complete content index at: https://stalin-pereira.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# The Beginner's Guide to API Design: REST Principles Most Developers Get Wrong
- URL: https://stalin-pereira.com/the-beginners-guide-to-api-design-rest-principles-most-developers-get-wrong/
- Published: 2026-02-04T06:28:00.000Z
- Updated: 2026-10-16T19:08:19.000Z
- Description: Covering resource naming HTTP verbs status codes and hypermedia that make APIs intuitive
- Author: Stalin Pereira
- Tags: Backend

**Your API Is Confusing**

And it's costing your team hours every week

## Imagine a Library

Where every librarian uses different rules to find books

- **No System** — One organizes by color, another by size, a third by author's birthday
- **Lost Time** — Every visitor spends 30 minutes just figuring out where to look
- **Frustration** — People stop coming because it's too hard to find anything

## APIs Work The Same

Inconsistent design makes developers struggle unnecessarily

- **Confusion** — Every endpoint follows different conventions and patterns
- **Documentation** — Hours wasted reading docs that shouldn't be needed
- **The Fix** — REST principles create predictable, intuitive interfaces

## Resource Naming Done Right

Nouns describe things, verbs describe actions on them

- **Use Nouns** — Resources are things: /users, /orders, /products
- **Stay Plural** — Collections use plural: /users not /user for consistency
- **Nest Logically** — Relationships are clear: /users/123/orders shows ownership

## Old Way vs New Way

Stop creating action-based endpoints

- **Old Way** — /getUserById, /createNewOrder, /deleteProduct - verbs everywhere
- **New Way** — /users/123, /orders, /products/456 - clean resources
- **Why Better** — HTTP verbs already tell us the action, no need to repeat

## HTTP Verbs Have Meaning

Each verb communicates a specific intent clearly

- **GET** — Retrieve data without changing anything on the server
- **POST** — Create new resources when you don't know the final ID
- **PUT/PATCH** — Update existing resources - full replacement or partial update
- **DELETE** — Remove resources permanently from the system

## Status Codes Tell Stories

Numbers communicate success or failure instantly

- **2xx Success** — 200 OK, 201 Created, 204 No Content - mission accomplished
- **4xx Client Error** — 400 Bad Request, 404 Not Found - caller made a mistake
- **5xx Server Error** — 500 Internal Error - something broke on your end

## The 200-Everything Trap

Returning 200 with error messages causes real problems

- **Hidden Failures** — Monitoring tools think everything is fine when it's not
- **Extra Parsing** — Clients must check response body for every single request
- **Lost Context** — Caching, retries, and error handling all break silently

## Hypermedia Guides Users

Include links to help clients discover what's possible next

- **Self Discovery** — Response includes links to related actions and resources
- **Reduced Coupling** — Clients don't hardcode URLs, they follow provided links
- **Evolvability** — Change your URL structure without breaking existing clients

## The Business Impact

Good API design directly affects your bottom line

- **Faster Onboarding** — New developers become productive in days, not weeks
- **Fewer Bugs** — Predictable patterns mean fewer integration mistakes
- **Happy Partners** — External developers actually want to build on your platform

## Design APIs Like Streets

Clear signs make navigation effortless for everyone

> Consistent naming, proper verbs, meaningful status codes, and helpful links create APIs that developers love to use.

---

What's the worst API naming convention you've encountered in your projects?