API Reference

This page contains the complete API reference for all custom endpoints that are running on the backend server. Once you have the server running locally, you can access the API via the following url: http://localhost:3001/api.

GET /

Root endpoint for health checks

Simple health check endpoint used by Cloud Run and load balancers

Status Codes:

• 200 OK – Service is running

GET /api/health

Health check endpoint

Checks API and database connectivity. Returns OK even if database is down (for Cloud Run health checks)

Status Codes:

• 200 OK – Service health status

POST /api/register

Register new user (Admin only)

Creates a new user account. Requires admin role.

Status Codes:

• 201 Created – User created successfully

• 400 Bad Request – Invalid input

• 401 Unauthorized – Unauthorized

• 403 Forbidden – Forbidden - Admin access required

• 409 Conflict – Username or email already exists

• 500 Internal Server Error – Server error

POST /api/login

User login

Authenticate user and receive JWT token. Logs all login attempts (success and failure).

Status Codes:

• 200 OK – Login successful

• 400 Bad Request – Missing username or password

• 401 Unauthorized – Invalid credentials

• 500 Internal Server Error – Server error

GET /api/me

Get current user

Returns the authenticated user’s information

Status Codes:

• 200 OK – User information

• 401 Unauthorized – Unauthorized

• 404 Not Found – User not found

• 500 Internal Server Error – Server error

GET /api/current-stock

Get current stock status

Retrieves the current stock status for all stores and items from the v_current_stock_status view

Status Codes:

• 200 OK – Current stock status

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/daily-summary

Get daily stock summary

Retrieves daily stock summary data for the specified number of days, optionally filtered by store

Query Parameters:

• days (integer) – Number of days to retrieve

• store (string) – Filter by store code

Status Codes:

• 200 OK – Daily stock summary

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/store-performance

Get store performance metrics

Retrieves performance metrics for all stores from the v_store_performance view

Status Codes:

• 200 OK – Store performance data

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/item-performance

Get item performance metrics

Retrieves performance metrics for items including out-of-stock events, tracking statistics, and date ranges

Query Parameters:

• limit (integer) – Maximum number of items to return

• startDate (string) – Filter from this date (YYYY-MM-DD)

• endDate (string) – Filter until this date (YYYY-MM-DD)

Status Codes:

• 200 OK – Item performance data

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/out-of-stock

Get recent out of stock events

Retrieves out of stock events from the last N hours, optionally filtered by store

Query Parameters:

• hours (integer) – Number of hours to look back

• store (string) – Filter by store code

Status Codes:

• 200 OK – Out of stock events (limited to 100 most recent)

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/time-windows

Get time window stock data

Retrieves stock status data grouped by time windows for analysis. Can filter by date range or specific date, and optionally by store

Query Parameters:

• days (integer) – Number of days to retrieve (ignored if date is provided)

• date (string) – Specific date to retrieve (YYYY-MM-DD). Overrides days parameter

• store (string) – Filter by store code

Status Codes:

• 200 OK – Time window stock data

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/weekly-trends

Get weekly stock trends

Retrieves weekly stock trends from the v_weekly_stock_trends view for the specified number of weeks

Query Parameters:

• weeks (integer) – Number of weeks to retrieve

• store (string) – Filter by store code

Status Codes:

• 200 OK – Weekly trends data

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/stores

Get list of stores

Returns a list of all unique store codes from the stock_status table

Status Codes:

• 200 OK – Array of store codes

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/weekly-sales-stores

Get weekly sales store names

Returns a list of all unique store names from the weekly_sales database

Status Codes:

• 200 OK – Array of store names

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/weekly-sales-years

Get available years from weekly sales

Returns a list of all available years in the weekly_sales database, sorted descending

Status Codes:

• 200 OK – Array of years

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/items

Get list of items

Returns a list of all unique items (item_id and item_name) from the stock_status table

Status Codes:

• 200 OK – Array of items with id and name

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/daily-sales

Get daily sales data

Retrieves daily sales data with catering/non-catering breakdown. Supports filtering by date range and store code

Query Parameters:

• days (integer) – Number of days to retrieve (used if startDate not provided)

• store (string) – Filter by store code

• startDate (string) – Start date (YYYY-MM-DD). Overrides days parameter

• endDate (string) – End date (YYYY-MM-DD)

Status Codes:

• 200 OK – Daily sales data

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/weekly-sales

Get weekly sales data

Retrieves weekly sales data from the weekly_sales database. Store parameter is required. Uses the same query structure as generate_visualizations.py

Query Parameters:

• store (string) – Store name (required) (Required)

• years (string) – Comma-separated list of years (e.g., “2024,2025”)

Status Codes:

• 200 OK – Weekly sales data

• 400 Bad Request – Store parameter is required

• 401 Unauthorized – Unauthorized

• 500 Internal Server Error – Server error

GET /api/login-logs

Get login logs (Admin only)

Retrieves login attempt logs with filtering options. Requires admin role.

Query Parameters:

• limit (integer) – Maximum number of logs to return

• username (string) – Filter by username

• type (string) – Filter by attempt type

• startDate (string) – Filter logs from this date (YYYY-MM-DD)

• endDate (string) – Filter logs until this date (YYYY-MM-DD)

Status Codes:

• 200 OK – Login logs

• 400 Bad Request – Invalid limit value

• 401 Unauthorized – Unauthorized

• 403 Forbidden – Forbidden - Admin access required

• 500 Internal Server Error – Server error

Source Code Links

Note

View Source Code: Each API endpoint is implemented in server.js. Click on any endpoint below to see its implementation details.

All API endpoints are defined in the following file:

• server.js - Main API server with all route handlers

Quick Reference - Endpoint Locations in server.js:

• GET / - Line 107

• GET /api/health - Line 116

• POST /api/register - Line 140 (Admin only)

• POST /api/login - Line 197

• GET /api/me - Line 294

• GET /api/current-stock - Line 315

• GET /api/daily-summary - Line 329

• GET /api/store-performance - Line 356

• GET /api/item-performance - Line 370

• GET /api/out-of-stock - Line 421

• GET /api/time-windows - Line 448

• GET /api/weekly-trends - Line 495

• GET /api/stores - Line 524

• GET /api/weekly-sales-stores - Line 539

• GET /api/weekly-sales-years - Line 554

• GET /api/items - Line 569

• GET /api/daily-sales - Line 585

• GET /api/weekly-sales - Line 637

• GET /api/login-logs - Line 690 (Admin only)