Resources Are Nouns, Not Verbs
Stripe's API is legendary among developers. Engineers routinely say it 'just makes sense.' The secret? Every URL describes a thing, not an action. You do not POST /charge-credit-card - you POST /charges. You do not GET /retrieve-customer-info - you GET /customers/cus_123. This consistent noun-based pattern means developers can guess new endpoints correctly without reading the docs.
The biggest mistake beginners make: designing APIs around actions instead of things. Your URL should describe the thing you are operating on. The HTTP method describes the action.
Identifying Your Resources
Start by listing the core entities in your system. For an e-commerce platform:
Each resource has a collection URL (/users) and an individual URL (/users/42). The collection supports GET (list) and POST (create). The individual supports GET (read), PUT/PATCH (update), and DELETE (remove).
Nested vs Flat Resources
Should it be /users/42/orders or just /orders?user_id=42? The rule of thumb:
Nest when the child CANNOT exist without the parent: /users/42/addresses (addresses belong to a user)
Keep flat when the child is independently queryable: /orders (you might want all orders, not just one user's orders)
Never nest more than 2 levels deep: /users/42/orders/7/items is getting unwieldy. Consider /order-items/7 instead
Nesting Decision Flowchart
Naming Conventions That Scale
Always plural: /users not /user, /products not /product
Lowercase with hyphens: /order-items not /orderItems or /order_items
No file extensions: /users not /users.json
No trailing slashes: /users not /users/
Use IDs in URLs: /users/42 not /users/john-smith (names change, IDs do not)
Handling Actions That Do Not Map to CRUD
Sometimes you need operations that are not simply create/read/update/delete. Here are three patterns, each with a real example:
Common Modeling Mistakes
Exposing database tables directly as resources - your API models should be stable even if your database schema changes
One-to-one mapping between UI screens and API endpoints - design resources around domain objects, not pages
Forgetting about bulk operations - if clients need to create 100 items, provide POST /items/batch instead of making them call POST /items 100 times
Overusing nested URLs - /v1/companies/3/departments/7/teams/12/members/42 is a nightmare to maintain. Flatten it.
Interview Tip
In API design interviews, start by listing your resources on the whiteboard as a table: Resource | URL | Methods. Then draw the relationships between them. Mention: 'I keep nesting to 2 levels max and use flat URLs with query parameters for resources that need independent querying.' This structured approach impresses interviewers.
Key Takeaway
Good API design starts with identifying your resources (nouns) and expressing operations through HTTP methods (verbs). Keep URLs consistent, use plurals, nest only when necessary, and model non-CRUD actions as sub-resources or state transitions. Study Stripe's API as the gold standard.