REST APIs - lesson 3 | HackIndia Skills

Key point

One idea

A status code is part of your API contract. It tells the client what happened before they read the response body.

Use the most specific common code your teammate will understand. Do not return 200 for every case.

The useful set

You do not need to memorise every HTTP status code. For a college project API, start with this small set.

2xx means the request worked. 4xx means the client sent something wrong. 5xx means your server failed while handling a valid-looking request.

Example

Common choices

Use these codes in your routes and docs. They cover most hackathon APIs like notes, events, expenses, bookings, and campus marketplace listings.

GET /api/v1/events
200 OK                  List returned

GET /api/v1/events/42
200 OK                  Event found
404 Not Found           No event with id 42

POST /api/v1/events
201 Created             Event created
400 Bad Request         Body is invalid JSON or missing required fields

PUT /api/v1/events/42
200 OK                  Event replaced or updated and returned
404 Not Found           Event does not exist

PATCH /api/v1/events/42
200 OK                  Event partially updated and returned
404 Not Found           Event does not exist

DELETE /api/v1/events/42
204 No Content          Event deleted, no response body
404 Not Found           Event does not exist

POST /api/v1/login
200 OK                  Login worked, token returned
401 Unauthorized        Login failed or token missing

GET /api/v1/admin/reports
403 Forbidden           User is logged in but not allowed

Your to-do

Choose a status

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Ask if the server understood the request.
Ask if the requested resource exists.
Ask if the user is logged in, if the route needs login.
Ask if the user is allowed to do this action.
Return a 2xx only when the action really worked.

0 of 5 done

Common mistake

Avoid fake success

A common mistake is returning 200 with a body like { "success": false }. That makes frontend code harder because it must inspect every body to know if the call failed.

Let the status code carry the main result. Use the body to explain details, especially for 4xx errors.

Example

Express example

Here is a small Express route. Notice how each branch exits with the right status.

app.get('/api/v1/events/:id', async (req, res) => {
  const event = await Event.findById(req.params.id);

  if (!event) {
    return res.status(404).json({
      error: 'Event not found'
    });
  }

  return res.status(200).json({
    data: event
  });
});

app.post('/api/v1/events', async (req, res) => {
  const { title, date } = req.body;

  if (!title || !date) {
    return res.status(400).json({
      error: 'title and date are required'
    });
  }

  const event = await Event.create({ title, date });

  return res.status(201).json({
    data: event
  });
});

Tip

Document the code

In your README, write the expected status beside each endpoint. This helps a teammate test your API with curl, Postman, Bruno, or a frontend.

If you use AI to draft the README, ask it to make a status table from your routes. Then check every row against your actual code.