REST APIs - lesson 7 | HackIndia Skills

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.