REST APIs - lesson 7 | HackIndia Skills

REST APIs - lesson 7 | HackIndia Skills | HackIndia

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:
...

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

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

Quick check