Backend API Overview

📌 What is this for? (Quick Summary for New Interns)

In Simple Words:
When the dashboard in your browser needs to fetch the latest speed or send a Start command, it talks to our cloud server using a REST API.

Instead of having 20 different web addresses for different tasks, we use one single endpoint:
POST https://npig3gpgck.execute-api.ap-south-1.amazonaws.com/api

In the request, we include an action name (like "FETCH_METRICS" or "SEND_CONTROL"). Our cloud code reads that action and does the work. This page explains how that single entry point works.

---

1. How a Request Looks

Every request sent to our API follows this simple JSON format:

{
  "action": "<NAME_OF_ACTION>",
  "payload": {
    "sessionId": "<TAB_ID>",
    "...": "Any extra numbers or settings needed for this action"
  }
}

And in the HTTP headers, you include your Cognito login token:

Authorization: Bearer <your_login_token>
Content-Type: application/json

---

2. Request Lifecycle Step-by-Step

sequenceDiagram
    autonumber
    participant Browser as Your Browser (Dashboard)
    participant APIGW as API Gateway (Front Door)
    participant Security as Security Token Check
    participant Lambda as Backend Code (PodDashboardRouter)
    participant Backend as Database / IoT

    Browser->>APIGW: POST /api (Sends action + token)
    APIGW->>Security: Is this token valid?
    alt Token Invalid / Expired
        Security-->>Browser: 401 Unauthorized (Please log in again)
    else Token OK
        APIGW->>Lambda: Runs our backend function
    end

    Note over Lambda: Check if user is logged in on another tab
    alt Another tab is active
        Lambda-->>Browser: 401 SESSION_SUPERSEDED (Log out old tab)
    else This tab is valid
        Lambda->>Backend: Fetch numbers or send command
        Backend-->>Lambda: Returns result
        Lambda-->>Browser: 200 OK (Sends data back to dashboard)
    end

---

3. List of Available Actions

Action Name	Who Can Call It?	What It Does
REGISTER_SESSION	Everyone	Tells the server: "This browser tab is now the active one."
FETCH_METRICS	Everyone	Fetches the newest speed, battery, and temperature readings.
FETCH_STATE	Everyone	Fetches whether the battery is currently on or the vehicle is running.
SEND_CONTROL	Admin / Engineer	Sends physical commands to the vehicle: Enable Battery, Launch, or Emergency Stop.
LOG_EVENT	Everyone	Saves a permanent record when a test run starts or stops.
LIST_USERS	Admin only	Lists all registered user accounts.
GET_USER_GROUPS	Admin only	Checks what permissions a specific user has.

---

4. Common Status Codes

• 200 OK: Everything worked as expected.
• 400 Bad Request: You forgot a required parameter (like omitting the sessionId).
• 401 Unauthorized: Your login token is expired, or you logged in from another tab.
• 403 Forbidden: You tried to perform an action you don't have permission for (e.g. a Manager trying to launch the vehicle).
• 500 Server Error: An unexpected crash or database connection timeout in the backend code.