REST APIs - lesson 5 | HackIndia Skills

Key point

One list rule

Keep one collection URL. Use query parameters to narrow or page the result.

Your teammate should call /api/v1/events?city=Pune&page=2&limit=10, not guess URLs like /pune-events/page-2.

What filtering does

Filtering lets users ask for a smaller list. Common filters are city, category, status, date, ownerId, or search text.

Use filters only on list endpoints. A single item URL like /api/v1/events/42 should not need filters.

Your to-do

Pick useful filters

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.

Start with the fields your UI actually shows as dropdowns, tabs, or search boxes.
Name filters the same way as response fields, like city, status, and category.
Use simple values first, like status=open, not complex JSON in the URL.
Ignore unknown filters or return a clear error, but be consistent.
Document one request and one response for each important filter.

0 of 5 done

Example

Express example

This example filters events by city and status. It also paginates the result.

For a real project, your data may come from MongoDB, Postgres, or an array. The API shape stays the same.

app.get('/api/v1/events', async (req, res) => {
  const page = Math.max(parseInt(req.query.page || '1', 10), 1);
  const limit = Math.min(Math.max(parseInt(req.query.limit || '10', 10), 1), 50);
  const skip = (page - 1) * limit;

  const filters = {};
  if (req.query.city) filters.city = req.query.city;
  if (req.query.status) filters.status = req.query.status;

  const total = await Event.countDocuments(filters);
  const events = await Event.find(filters)
    .sort({ createdAt: -1 })
    .skip(skip)
    .limit(limit);

  res.status(200).json({
    data: events,
    meta: {
      page,
      limit,
      total,
      totalPages: Math.ceil(total / limit)
    }
  });
});

Pagination shape

Pagination stops your API from returning 5,000 rows when a teammate only needs the first screen. This keeps the API faster and easier to test on college Wi-Fi.

For this track, page and limit are enough. Cursor pagination is useful later for large feeds, but do not add it unless you need it.

Tip

Return metadata

Always return the list inside data and paging details inside meta. This gives frontend teammates the numbers they need for Next, Previous, and page count.

Set a safe maximum limit. If someone sends limit=10000, cap it to something like 50 or 100.

Common mistake

Do not return a bare array for paginated endpoints. It hides important details like total count and current page.

Also avoid changing response shapes between filters. /events and /events?city=Mumbai should return the same structure.