1. REST Principles
REST stands for Representational State Transfer. It's an architectural style โ a set of rules for how clients and servers communicate over HTTP. When an API follows these rules consistently, it's called a RESTful API.
REST was defined by Roy Fielding in his 2000 doctoral dissertation, and it became the dominant style for web APIs because it maps naturally to HTTP. Every API you'll ever consume โ Stripe, Twilio, GitHub, Shopify โ is a REST API.
UrbanCart has a React frontend, a Node/Express backend, and a mobile app in the works. All three need to talk to the same data. A well-designed REST API means the React app, mobile app, and any future partners can all use the same endpoints with predictable, consistent behavior.
The four principles you need to know:
Stateless
Each request must contain everything needed to understand it. The server stores no client session state. If you need authentication, send the token with every request โ the server doesn't remember your previous request.
Resource-Based URLs
A URL identifies a thing (a resource), not an action. /products identifies the products collection. /products/42 identifies product 42. The URL is a noun, not a verb.
Uniform Interface
HTTP verbs define the action. GET, POST, PUT, PATCH, DELETE mean the same thing across every resource. You don't invent new verbs โ you combine existing verbs with resource URLs.
Client-Server Separation
The frontend and backend are independent. The React app doesn't know how the database works. The API doesn't know how the UI renders data. Either side can change without breaking the other, as long as the API contract stays the same.
React / Mobile
verb + URL + body
Node.js server
status + data
2. Resource Naming
The URL is the public face of your API. Good resource naming makes an API intuitive โ a developer can guess the right endpoint without reading documentation.
Nouns, not verbs
The single most common REST mistake is putting verbs in URLs. The HTTP method already expresses the action. The URL should express the resource.
Wrong โ Verb in URL
/getProducts/createProduct/deleteProduct?id=5/updateProductPrice
Correct โ Noun URL + HTTP verb
GET /productsPOST /productsDELETE /products/5PATCH /products/5
Additional naming rules
- Plural nouns โ use
/products, not/product. The collection is plural even when you access a single item (/products/42). - Lowercase โ URLs are case-sensitive on most servers. Always lowercase to avoid confusion.
- Hyphens for multi-word โ use
/product-reviewsnot/productReviewsor/product_reviews. Hyphens are URL-safe and readable. - Hierarchy for relationships โ nested resources reflect ownership.
/products/42/reviewsmeans "reviews belonging to product 42." - No trailing slash โ
/productsis correct;/products/is not.
/api/products โ product collection. /api/products/42 โ single product. /api/products/42/reviews โ reviews for that product. The /api prefix distinguishes API routes from page routes.
3. HTTP Methods
HTTP gives you five verbs that map directly to the four CRUD operations. Choosing the right verb matters โ clients, caches, and proxies treat them differently based on their semantic meaning.
| Method | CRUD | UrbanCart Example | Idempotent? |
|---|---|---|---|
| GET | Read | Fetch product list or a single product | Yes โ safe to repeat |
| POST | Create | Add a new product to the catalogue | No โ creates a new resource each time |
| PUT | Replace | Replace all fields of product 42 | Yes โ same result every time |
| PATCH | Partial update | Update only the price of product 42 | Usually yes |
| DELETE | Delete | Remove product 42 from the catalogue | Yes โ deleting twice has the same result |
4. HTTP Status Codes
Status codes tell the client what happened. A proper REST API never returns 200 OK with an error inside the body โ the status code itself should be meaningful. Clients write their error handling based on these codes.
| Code | Name | When to use in UrbanCart |
|---|---|---|
| 200 OK | OK | Successful GET, PATCH, DELETE with a response body |
| 201 Created | Created | POST created a new product; include the new resource in the response |
| 400 Bad Request | Bad Request | Malformed JSON, missing required fields, invalid data types |
| 401 Unauthorized | Unauthorized | No auth token provided, or token is invalid/expired |
| 403 Forbidden | Forbidden | Token is valid, but this user doesn't have permission (non-admin tries to delete a product) |
| 404 Not Found | Not Found | GET /api/products/9999 where product doesn't exist |
| 422 Unprocessable Entity | Unprocessable Entity | Request body is valid JSON but fails validation rules (price < 0, name is empty string) |
| 500 Internal Server Error | Internal Server Error | Database connection dropped, unhandled exception โ something broke on our side |
5. Request Validation
Validation is the gatekeeper of your API. Every POST and PATCH request needs validation before you touch the database. Without it, you'll store garbage data, crash on null values, or open security holes.
Good validation does three things:
- Checks presence โ required fields must exist and not be empty strings.
- Checks types and ranges โ price must be a number and must be non-negative; name must be a string under 200 characters.
- Returns specific errors โ tell the client exactly what's wrong, not just "bad request."
6. Pagination
UrbanCart has thousands of products. Returning all of them in one request would be slow, expensive, and unusable in the UI. Pagination splits the results into pages, letting clients request exactly what they need.
The industry-standard approach uses query string parameters: ?page=1&limit=10. The response includes metadata so the client knows how many total results exist and how many pages there are.
data, total, page, limit, pages โ is the standard shape used by most production APIs.
7. Filtering & Sorting
Pagination controls how many results you get. Filtering and sorting control which results you get, and in what order. Both use query string parameters, and both work on top of pagination.
req.query.sort directly to your database query โ it's a SQL/NoSQL injection risk. Always check that the value is in an approved list of column names before using it.
8. Complete CRUD API โ UrbanCart Products
Let's put it all together. The full UrbanCart Products API has 7 endpoints covering every operation a client might need. Below is the complete implementation followed by curl examples for each endpoint.
Live API examples with curl
app.use('/api/products', require('./routes/products')); to your Express app. The router handles everything under that prefix automatically.
Quiz
You completed the REST API Design quiz.
You just designed a production-grade REST API.
Now build a full-stack career that scales.
Join the Best AI Programs โ three 5-month courses, fully online, with placement assistance. Week 1 is free.
Explore our AI-era courses โ