Harman Panwar

Posted on May 10

REST API Design Made Simple with Express.js

#webdev #javascript #beginners #api

If you've ever wondered how your frontend app talks to a database or how your phone knows your profile information, you've touched an API. When that API follows a specific set of rules called REST, it becomes predictable, clean, and powerful.

In this post, we'll break down REST APIs from the ground up, using a single resource --- users --- as our running example.

What Is a REST API?

API stands for Application Programming Interface. Think of it as a waiter in a restaurant:

You (the client) place an order.
The waiter (the API) takes it to the kitchen.
The kitchen (the server) prepares the response.
The waiter brings it back to you.

REST (Representational State Transfer) is a set of architectural rules that make APIs simple and scalable. When an API is RESTful, it means:

It uses standard HTTP methods (like GET, POST, etc.).
It organizes data into resources (like users, orders, products).
Each resource has a unique address (URL).

🔁 REST APIs enable communication between a client (e.g., browser, mobile app) and a server over HTTP.

Resources: The Heart of REST

In REST, everything is a resource. A resource is any piece of data you can name --- a user, a photo, a comment, a product.

Each resource has:

A unique identifier (e.g., a user ID).
A representation (e.g., JSON or XML data).

For our example, the resource is users.

Example of a user representation in JSON:

{
  "id": 101,
  "name": "Alex Rivera",
  "email": "alex@example.com"
}

HTTP Methods: What Action Do You Want to Perform?

HTTP methods tell the server what kind of operation you want on a resource. Here are the four most common ones:

Method	Action	SQL Analogy
GET	Read data	SELECT
POST	Create data	INSERT
PUT	Update all or replace	UPDATE
DELETE	Remove data	DELETE

1. GET -- Retrieve a user


GET /users/101

2. POST -- Create a new user

POST /users

3. PUT -- Update user (full update)

http

PUT /users/101

4. DELETE -- Remove a user


DELETE /users/101

✨ Convention tip: Use PUT for full updates and PATCH for partial updates. But for simple APIs, PUT is fine.

Status Codes: What the Server Says Back

Status codes are three-digit numbers that summarize the result of your request. You don't need to memorize them all --- just the key ones:

Code	Meaning	When?
200	OK	GET, PUT, DELETE succeeded
201	Created	POST created a new user
400	Bad Request	Client sent invalid data
401	Unauthorized	Missing or bad authentication
404	Not Found	User ID doesn't exist
500	Internal Server Error	Something broke on the server side

Example response after creating a user:


Status: 201 Created
Body: { "id": 102, "name": "Jamie", "email": "jamie@example.com" }

Designing RESTful Routes for "users"

REST encourages clean, predictable URLs based on resources, not actions.

Purpose	HTTP Method	URL
List all users	GET	`/users`
Get a specific user (id = 5)	GET	`/users/5`
Create a new user	POST	`/users`
Fully update user 5	PUT	`/users/5`
Delete user 5	DELETE	`/users/5`

Notice:

No verbs in URLs (avoid /getUser, /deleteUser).
Use plural nouns (/users instead of /user).
The ID identifies a single user.

Putting It All Together: A Complete Interaction

Let's walk through a realistic client-server conversation for a user profile.

1. Client creates a new user


POST /users
Content-Type: application/json

{
  "name": "Casey Kim",
  "email": "casey@example.com"
}

Server response:

HTTP/1.1 201 Created
Location: /users/203

{
  "id": 203,
  "name": "Casey Kim",
  "email": "casey@example.com"
}

2. Client retrieves that user

GET /users/203

Server response:

HTTP/1.1 200 OK

{
  "id": 203,
  "name": "Casey Kim",
  "email": "casey@example.com"
}

3. Client updates the user's email


PUT /users/203
Content-Type: application/json

{
  "name": "Casey Kim",
  "email": "casey.kim@newdomain.com"
}

Server response:

HTTP/1.1 200 OK

{
  "id": 203,
  "name": "Casey Kim",
  "email": "casey.kim@newdomain.com"
}

4. Client deletes the user


DELETE /users/203

Server response:

HTTP/1.1 200 OK

Best Practices Recap

✅ Use nouns for resources (/users, not /createUser).\
✅ Keep URLs hierarchical (/users/5/posts for posts by user 5).\
✅ Return the correct status code (201 for creation, 404 for missing).\
✅ Use HTTP methods intentionally --- GET should never change data.\
✅ Version your API if needed (/v1/users).

Conclusion

REST APIs turn the messy problem of client-server communication into a clean, standardized conversation. By focusing on resources, using HTTP methods correctly, and returning meaningful status codes, you build APIs that are self-explanatory and easy to consume.

Whether you're fetching a list of users or deleting one, REST gives you a predictable recipe --- and that's a win for every developer on your team.

DEV Community