All the reading

REST APIs

8 lessons, about 35 minutes. The check's questions come from these.

Finding resources and routes

1. Think in resources

5 min

Start with nouns

Before you choose URLs or status codes, decide what things your API manages. These things are resources.

A resource is usually a noun your teammate can point to: student, event, team, payment, submission. It is not an action like register, pay, approve, or search.

Key point

One idea

Design the API around resources, not screens or buttons. Actions usually become changes to a resource, or creation of a related resource.

Example

Hackathon example

Imagine you are building a college hackathon API. A beginner might list features like this: create event, register team, approve project, view submissions.

Now rewrite them as resources. This gives you a cleaner base for routes later.

Feature idea -> Resource

create event -> events
register team -> registrations
approve project -> projects or reviews
view submissions -> submissions
add team member -> team_members
track UPI payment -> payments

Your to-do

Find resources

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.

Write the main user goal in one line.
Circle the nouns in that line.
Keep nouns that your API must store, show, update, or delete.
Merge duplicates, like participant and user if they mean the same thing.
Drop UI words, like dashboard, page, form, tab, and button.

0 of 5 done

2. Choose URLs and methods

4 min

Key point

One rule

Use nouns in URLs. Use HTTP methods for actions.

Your URL says what resource is being touched. The method says what is happening to it.

URLs are addresses

A resource-based URL points to a thing your API manages: users, teams, events, expenses, orders, submissions.

Keep URLs predictable. A teammate should guess the next route without opening five files.

Your to-do

Choose the URL

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 collection name, usually plural: /projects, /orders, /expenses.
Use an id for one item: /projects/{projectId}.
Nest only when the child clearly belongs to the parent: /projects/{projectId}/tasks.
Keep words lowercase and use hyphens if needed: /team-members.
Avoid verbs like /getProjects, /createOrder, or /deleteTask.

0 of 5 done

Reading status codes

3. Return the right status

5 min

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.

Shaping lists and docs

4. Shape requests and responses

4 min

Key point

One stable shape

Make every request and response easy to guess. Use clear field names, consistent types, and the same wrapper style across your API.

Your teammate should not need to inspect your database to know what to send or what they will get back.

Requests are contracts

A request body is not a form dump. It is the minimum data your API needs to create or update a resource.

Do not accept fields that the server should decide, like id, createdAt, ownerId, or status if the user is not allowed to set it.

Your to-do

Shape request bodies

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.

10 questions, 7 to pass.

Tip

Use AI carefully

You can ask ChatGPT, Gemini, or Claude to extract resources from your app idea. Do not accept the first list blindly.

Check if each item is a real thing your API stores or returns. Remove vague words like data, info, record, manager, and service.

Prompt:
I am building a REST API for a college hackathon project.
App idea: Teams register for events, submit projects, judges review submissions, and organisers publish results.
List the main API resources as nouns.
For each resource, say what it represents.
Avoid actions, screens, and UI terms.

Example

Resource map

A resource map is a small planning file. Add it to your repo before coding. It helps a teammate understand your API shape quickly.

You can name it API_PLAN.md or RESOURCE_MAP.md.

API resource map

App: Campus hackathon manager

Resources:
- users: students, organisers, and judges who log in
- events: hackathons or coding rounds hosted by the college
- teams: groups of users who participate together
- registrations: a team joining an event
- submissions: project links submitted by teams
- reviews: judge feedback and scores for a submission
- payments: optional fee payment records, if the event charges in rupees

Not resources:
- dashboard: this is a screen
- registerTeam: this is an action
- getWinners: this is a query or result view, not a core stored thing yet

Example

Method map

Use this as your first route list. Change the resource names to fit your project.

GET    /api/v1/projects              List projects
POST   /api/v1/projects              Create a project
GET    /api/v1/projects/{projectId}  Get one project
PATCH  /api/v1/projects/{projectId}  Update part of a project
DELETE /api/v1/projects/{projectId}  Delete a project

GET    /api/v1/projects/{projectId}/tasks             List tasks in a project
POST   /api/v1/projects/{projectId}/tasks             Create a task in a project
PATCH  /api/v1/projects/{projectId}/tasks/{taskId}    Update a task
DELETE /api/v1/projects/{projectId}/tasks/{taskId}    Delete a task

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

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
  });
});

Example

Create request example

For a college event API, the client should send event details. The server should create the id and timestamps.

POST /v1/events
Content-Type: application/json

{
  "title": "AI Project Demo Day",
  "date": "2026-02-12",
  "venue": "Seminar Hall 2",
  "feeRupees": 0,
  "tags": ["ai", "college", "demo"]
}

Example

Response examples

A single resource response can be simple. A list response should use a stable wrapper.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "data": {
    "id": "evt_101",
    "title": "AI Project Demo Day",
    "date": "2026-02-12",
    "venue": "Seminar Hall 2",
    "feeRupees": 0,
    "tags": ["ai", "college", "demo"],
    "createdAt": "2026-01-20T10:30:00Z"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "evt_101",
      "title": "AI Project Demo Day",
      "date": "2026-02-12",
      "venue": "Seminar Hall 2",
      "feeRupees": 0,
      "tags": ["ai", "college", "demo"]
    }
  ]
}

5. Add filtering and pagination

4 min

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.

Your to-do

Do this now

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.

Choose one list endpoint in your project, like /api/v1/events or /api/v1/ideas.
Add two useful filters using query parameters.
Add page and limit with defaults, such as page=1 and limit=10.
Return data and meta in the response.
Add one filtered, paginated example to your API documentation.

0 of 5 done

6. Version and handle errors

4 min

Key point

One rule

Use versions for planned change. Use errors for clear recovery.

A teammate should know two things from every failed call: what went wrong, and what they can do next.

Version with the URL

For a hackathon API, put the version in the path: /api/v1. It is easy to see, easy to test in Postman or curl, and simple to document.

Start with v1. Do not create v2 until you make a breaking change, such as renaming fields, removing fields, or changing how a URL works.

Common mistake

Avoid fake versions

Do not add /v2 just because you changed internal code or database tables. If the request and response still work the same for users, keep it as v1.

Also avoid mixing styles like /api/v1/events and /api/events?version=1 in the same project. Pick one style and stay with it.

Your to-do

Create error rules

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.

Return JSON for every error, not plain text.
Include a stable code, a human message, and optional details.
Use the right status code: 400, 401, 403, 404, 409, 422, or 500.
Do not leak secrets, stack traces, database URLs, or tokens.
Log the full server error privately, but return a safe message to the caller.

0 of 5 done

Example

Error response shape

Use one shape across the API. This helps your frontend teammate handle errors without writing special code for every route.

Here is a simple format you can copy into your docs and backend.

{
  "error": {
    "code": "EVENT_NOT_FOUND",
    "message": "No event found with id evt_123.",
    "details": {
      "id": "evt_123"
    }
  }
}

Example

Express example

This example shows versioned routes and one shared error handler. Keep the response format the same for validation errors, missing resources, and server errors.

If you use AI to generate this, ask it to add test requests too. Check that it does not return HTML error pages.

import express from "express";

const app = express();
app.use(express.json());

const events = [
  { id: "evt_1", title: "College Hack Night", city: "Pune" }
];

app.get("/api/v1/events/:id", (req, res, next) => {
  const event = events.find(e => e.id === req.params.id);

  if (!event) {
    return res.status(404).json({
      error: {
        code: "EVENT_NOT_FOUND",
        message: `No event found with id ${req.params.id}.`,
        details: { id: req.params.id }
      }
    });
  }

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

app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({
    error: {
      code: "INTERNAL_ERROR",
      message: "Something went wrong. Try again later."
    }
  });
});

app.listen(3000, () => console.log("API running on port 3000"));

Tip

Use boring codes

Make error codes stable and readable: EVENT_NOT_FOUND, INVALID_PAGE, EMAIL_ALREADY_USED. Your message can change later, but the code should not break client logic.

For validation errors, add details per field. For example, title is required, price must be a number, or page must be at least 1.

Your to-do

Do this now

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.

Prefix your routes with /api/v1.
Add one shared error response shape to your code and docs.
Create one 404 error for a missing resource.
Create one 400 or 422 error for a bad request, such as invalid page.
Add two curl or Postman examples showing failed calls and JSON errors.

0 of 5 done

7. Document for a teammate

5 min

Key point

One job

Your API docs should help a teammate run the project and make the first successful request in 10 minutes.

Good docs are not long. They are accurate, runnable, and copied from the real API, not from memory.

What to document

For a hackathon repo, keep docs in README.md unless the API is large. A teammate should not need Postman screenshots to understand your API.

Cover these parts: project purpose, local setup, base URL, version, auth if any, endpoints, query params, request bodies, response examples, error format, and known limits.

Your to-do

Build the README

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 a one-line project summary and who the API is for.
Add setup commands from a fresh clone, including env variables with safe dummy values.
List the base URL, such as http://localhost:3000/api/v1.
Document each endpoint with method, path, purpose, inputs, success response, and errors.
Add one curl example that a teammate can copy and run.

0 of 5 done

Example

Endpoint doc example

This format is enough for most college projects. Keep the examples small but real.

Use the same field names your API returns. If your API says pageSize, do not write limit in the docs.

GET /api/v1/events

Returns events for the current page.

Query params:
- city: optional, filter by city, example: Pune
- page: optional, default 1
- limit: optional, default 10, max 50

Example request:
curl "http://localhost:3000/api/v1/events?city=Pune&page=1&limit=2"

Success response: 200 OK
{
  "data": [
    {
      "id": "evt_101",
      "title": "Backend Build Night",
      "city": "Pune",
      "date": "2026-02-12"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 18
  }
}

Error response: 400 Bad Request
{
  "error": {
    "code": "INVALID_QUERY",
    "message": "limit must be between 1 and 50"
  }
}

Tip

Use AI carefully

You can ask ChatGPT, Gemini, or Claude to turn your routes into README docs. Paste your route files and one sample response from your running API.

Then check the output manually. AI often invents fields, status codes, auth rules, and setup commands. Your docs must match the repo exactly.

Prompt:
Create a README API documentation section from these Express routes.
Include method, path, query params, request body, success response, error response, and curl examples.
Do not invent fields. If something is missing, mark it as TODO.

Paste routes here:
...

Paste real API response here:
...

Common mistake

Avoid hidden knowledge

Do not write docs that only you can understand. Your teammate may be on a hostel Wi-Fi connection with a clean laptop and no context.

Common missing details are database setup, .env keys, seed data, and which port the server uses. Put safe examples in the README and keep secrets out of Git.

Example

Setup section sample

Your setup section should work from a fresh clone. Test it once in a new folder before submission.

If you use a database or external API, show dummy values and explain what must be replaced.

## Run locally

1. Clone the repo
2. Install dependencies

npm install

3. Create .env

PORT=3000
DATABASE_URL=your_local_database_url
JWT_SECRET=change_this_for_local_dev

4. Start the server

npm run dev

Base URL:
http://localhost:3000/api/v1

Health check:
curl http://localhost:3000/api/v1/health

Your to-do

Do this now

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.

Open your repo README and add a Base URL section with the API version.
Pick two main endpoints and document method, path, inputs, success response, and error response.
Run your API and copy one real curl request and response into the README.
Ask an AI tool to review the docs for missing setup steps, then verify each suggestion.
Send the README to one teammate and ask them to run one request without your help.

0 of 5 done

8. Ship the API repo

4 min

Key point

One repo test

A good API repo passes one test: can a teammate clone it, run it, and call one endpoint in under 10 minutes.

Do not make the reviewer guess ports, env names, seed data, or example requests. Put the path in the repo.

What to ship

Your project is not only server code. It is a small product package. The repo should prove that your API works and that your design is clear.

Keep it simple. A Node, Python, Java, or Go API is fine. Use free tools. The important part is that the repo is public, runnable, and documented.

Your to-do

Repo checklist

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.

Add a README with setup, run command, base URL, and API examples.
Add docs that show URLs, methods, status codes, request bodies, response bodies, errors, and pagination or filtering.
Add versioning in the URL or routing, such as /api/v1/tasks.
Add seed data or clear instructions to create test data.
Add a smoke test command or curl file so a teammate can verify the API quickly.

0 of 5 done

Example

README starter

Use this as a minimum README shape. Edit names, commands, and endpoints for your API.

# Campus Tasks API

A small REST API for managing campus club tasks.

## Run locally

1. Install dependencies
   npm install

2. Copy env file
   cp .env.example .env

3. Start the server
   npm run dev

Base URL: http://localhost:3000/api/v1

## Try it

List tasks with pagination:
curl "http://localhost:3000/api/v1/tasks?page=1&limit=5"

Create a task:
curl -X POST "http://localhost:3000/api/v1/tasks" \
  -H "Content-Type: application/json" \
  -d '{"title":"Book seminar hall","dueDate":"2026-02-10"}'

## Example error

Request:
POST /api/v1/tasks
{}

Response: 400 Bad Request
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title is required"
  }
}

Tip

Use AI carefully

Ask ChatGPT, Gemini, or Claude to review your README as a new teammate. Paste your README and ask: “Can you run and call this API from a fresh clone? What is missing?”

Check the answer yourself. AI may assume scripts or files that do not exist. Only keep suggestions that match your actual repo.

Common mistake

Common shipping mistakes

Many good APIs lose points because the repo is hard to run. A reviewer should not need to DM you for the port, database setup, or sample request.

Do not only upload screenshots or a Postman collection. Your public repo must contain working code and clear written docs.

Example

Smoke test file

Add a small file like scripts/smoke.sh. It proves the API starts and one important endpoint responds.

#!/bin/sh

BASE_URL=${BASE_URL:-http://localhost:3000/api/v1}

echo "Checking health..."
curl -i "$BASE_URL/health"

echo "Listing tasks..."
curl -i "$BASE_URL/tasks?page=1&limit=5"

Your to-do

Do this now

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.

Open your repo and run it from a fresh terminal using only the README.
Fix one missing setup step, env variable, or command you find.
Add one curl example for a successful request and one for an error response.
Commit your README, docs, seed instructions, and smoke test file.
Ask a teammate to clone the repo and call one endpoint before you submit.

0 of 5 done

REST APIs

1. Think in resources

Start with nouns

One idea

Hackathon example

Find resources

2. Choose URLs and methods

One rule

URLs are addresses

Choose the URL

3. Return the right status

One idea

The useful set

Common choices

4. Shape requests and responses

One stable shape

Requests are contracts

Shape request bodies

Common mistake

Use AI carefully

Resource map

Do this now

Choose the method

Method map

Common mistake

Test by reading

Do this now

Choose a status

Avoid fake success

Express example

Document the code

Do this now

Create request example

Responses should be predictable

Response examples

Avoid shape drift

Use AI carefully

Do this now

5. Add filtering and pagination

One list rule

What filtering does

Pick useful filters

Express example

Pagination shape

Return metadata

Common mistake

Do this now

6. Version and handle errors

One rule

Version with the URL

Avoid fake versions

Create error rules

Error response shape

Express example

Use boring codes

Do this now

7. Document for a teammate

One job

What to document

Build the README

Endpoint doc example

Use AI carefully

Avoid hidden knowledge

Setup section sample

Do this now

8. Ship the API repo

One repo test

What to ship

Repo checklist

README starter

Use AI carefully

Common shipping mistakes

Smoke test file

Do this now