Skip to main content

​
Introduction

The SmartShelf API is a RESTful API built with Express.js that provides comprehensive inventory management capabilities. It follows REST principles and returns JSON-formatted responses for all endpoints.

​
Base URL

http://localhost:5000/api
All API endpoints are prefixed with /api. The default port is 5000 but can be configured via environment variables.

​
API Architecture

SmartShelf API is built using:
  • Express.js - Web framework
  • MongoDB - Database with Mongoose ODM
  • JWT - Token-based authentication
  • Helmet - Security headers
  • CORS - Cross-origin resource sharing
  • express-rate-limit - Request throttling

​
RESTful Design Principles

The API follows REST conventions:
  • Resources are represented as nouns (e.g., /inventory, /tasks, /users)
  • HTTP methods indicate actions:
    • GET - Retrieve resources
    • POST - Create new resources
    • PUT - Update existing resources
    • DELETE - Remove resources
  • Stateless requests with authentication via JWT tokens
  • Consistent URL structure and naming conventions

​
Response Format Standards

​
Success Response

All successful responses follow this structure: 
{
  "success": true,
  "message": "Description of the operation",
  "data": {
    // Response payload (optional)
  }
}
Example: 
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "email": "[email protected]",
      "role": "Manager"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

​
Error Response

All error responses follow this structure: 
{
  "success": false,
  "message": "Error description",
  "errors": [
    // Optional array of detailed errors
  ]
}
Example: 
{
  "success": false,
  "message": "Please provide all required fields"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
​
200
OK
Request succeeded
​
201
Created
Resource successfully created
​
400
Bad Request
Invalid request parameters or validation failed
​
401
Unauthorized
Authentication required or invalid credentials
​
403
Forbidden
Authenticated but not authorized for this action
​
404
Not Found
Requested resource does not exist
​
500
Internal Server Error
Server error occurred

​
Rate Limiting

To prevent abuse, the API implements rate limiting:
  • Window: 15 minutes
  • Limit: 100 requests per IP address
  • Headers: Standard rate limit headers included in responses
    • RateLimit-Limit - Total requests allowed
    • RateLimit-Remaining - Requests remaining
    • RateLimit-Reset - Time when limit resets
When the limit is exceeded, you’ll receive: 
{
  "success": false,
  "message": "Too many requests from this IP, please try again later."
}

​
API Versioning

Currently, the API is at version 1.0.0. The base path /api serves the current version. Future versions may introduce versioned paths like /api/v2 to maintain backward compatibility.

​
Quick Start Example

Here’s a simple example to get started with the SmartShelf API:

​
1. Check API Health

curl http://localhost:5000/health
Response: 
{
  "success": true,
  "message": "SmartShelf API is running",
  "timestamp": "2026-03-03T10:30:00.000Z",
  "environment": "development"
}

​
2. Register a New User

curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "securepass123"
  }'

​
3. Make Authenticated Request

curl http://localhost:5000/api/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

​
Endpoint Documentation

Explore detailed documentation for each API module:

Authentication

User registration, login, and JWT token management

Inventory

Product and stock management endpoints

Users

User management and role-based access control

Tasks

Task assignment and tracking

Alerts

Low stock and system alerts

Analytics

Business intelligence, reporting, and demand forecasting

​
Security

The API implements multiple security measures:
  • Helmet.js - Sets security HTTP headers
  • CORS - Configured for trusted origins only
  • JWT - Secure token-based authentication
  • bcryptjs - Password hashing with salt
  • Rate limiting - Protection against DoS attacks
  • Input validation - Using express-validator
  • HttpOnly cookies - Secure token storage option

​
Support

For issues or questions:
  • Check the Authentication Guide for auth-related questions
  • Review endpoint-specific documentation for detailed parameters
  • Ensure your requests include proper headers and authentication tokens

Build docs developers (and LLMs) love

Get started for freeTalk to us