REST APIs - lesson 4 | HackIndia Skills

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.

Use JSON for request bodies.
Name fields in one style, like camelCase, across all endpoints.
Accept only fields the client is allowed to set.
Mark which fields are required in your docs.
Keep nested objects only when they are useful to the caller.

0 of 5 done

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"]
}

Responses should be predictable

Return the resource after create or update. Return the same field names and types every time.

For list endpoints, return an object, not a bare array. This gives you space to add pagination metadata in the next lesson without breaking clients.

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"]
    }
  ]
}

Common mistake

Avoid shape drift

Shape drift is when one endpoint returns eventId, another returns id, and a third returns _id. This makes frontend code messy.

Pick one public API shape. If your database uses _id, convert it before sending the response.

Tip

Use AI carefully

You can ask ChatGPT or Gemini to draft sample JSON for your API docs. Then check every field yourself.

Check that examples do not include server-only fields in requests, fake status codes, changing field names, or data types that do not match your code.