System Design - lesson 2 | HackIndia Skills

Key point

Contract first

An API is a contract between two parts of your system. Write the contract before you code the route.

For a hackathon project, a good API contract says who calls it, what data goes in, what comes back, and what can fail.

Where APIs sit

In your system sketch, draw arrows between client, server, database, payment service, auth service, and any worker. Each arrow that crosses a boundary usually needs an API or a message format.

Do not list every internal function. Focus on the calls another part depends on. Your React app calling your Express server is an API. Your server calling Razorpay or a college ERP endpoint is also an API.

Your to-do

Define each endpoint

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.

Name the user action, such as create booking or mark attendance.
Choose the method: GET to read, POST to create, PATCH to update part, DELETE to remove.
Write the path using nouns, not actions, such as /api/bookings, not /api/createBooking.
List the request body, path params, query params, and required headers.
Write one success response and two common error responses.
Add who owns it: client, backend, worker, or third-party service.

0 of 6 done

Example

API contract example

Here is a small contract for a mess meal booking app. Keep this in your README or docs/api.md so judges can see your design without reading all code.

Endpoint: POST /api/bookings
Caller: Mobile or web client
Owner: Backend API
Purpose: Book a meal slot for a student

Headers:
Authorization: Bearer <token>
Content-Type: application/json

Request body:
{
  "mealDate": "2026-02-10",
  "slot": "lunch",
  "messId": "mess_a"
}

Success: 201 Created
{
  "bookingId": "bk_123",
  "status": "confirmed",
  "mealDate": "2026-02-10",
  "slot": "lunch"
}

Errors:
400 Bad Request: missing mealDate or invalid slot
401 Unauthorized: missing or invalid token
409 Conflict: slot already booked

Tip

Use AI carefully

Ask an AI tool to draft API contracts from your feature list. Then check every endpoint yourself.

Check that paths are consistent, errors are realistic, private data is not returned, and the response has enough data for the UI. AI often invents fields that are not in your database.

Prompt:
I am building a hackathon app for college mess meal booking.
Features: login, view meal slots, book a slot, cancel a booking, admin sees daily count.
Draft REST API contracts with method, path, request body, success response, and common errors.
Keep it simple for a Node.js backend and React client.

Common mistake

Common API mistakes

Beginners design APIs only for the happy path. Real systems need clear failure cases because the client must know what to show the user.

Another mistake is leaking database shape directly. Your API response should serve the client screen, not expose every column in your table.

Show trade-offs early

Your API design already has trade-offs. REST is simple and easy to judge. GraphQL can reduce over-fetching, but it adds setup and query control work.

For most hackathon submissions, REST with clear JSON contracts is enough. If you choose something else, write why.