simple-api-backend

Simple Frontend-Backend Application

A simple full-stack application demonstrating how frontend (HTML/CSS/JavaScript) communicates with backend (Express.js API).

Features

Backend:

• RESTful API with Express.js
• SQLite database for persistent data storage
• API versioning (currently v1)
• Semantic versioning with automated workflows
• Version endpoint (/api/version)
• CORS enabled
• JSON request/response handling
• Example endpoints for Users and Posts
• Easy to extend with new versions

Version Management:

• Semantic versioning (MAJOR.MINOR.PATCH)
• GitHub Actions for automated versioning
• Frontend version display
• Version API endpoint
• Automated release creation

Frontend:

• Clean, modern UI
• Interactive forms for creating users and posts
• Real-time data fetching from backend API
• Demonstrates frontend-backend communication
• No build process required (vanilla JavaScript)

Project Structure

.
├── server.js              # Main server file
├── database.js            # SQLite database setup and initialization
├── data.db               # SQLite database file (created automatically)
├── routes/
│   └── v1/               # Version 1 routes
│       ├── index.js      # V1 router
│       ├── users.js      # User endpoints (uses SQLite)
│       └── posts.js      # Post endpoints (uses SQLite)
├── public/               # Frontend files
│   ├── index.html        # Main HTML page
│   ├── style.css         # Styling
│   └── app.js            # Frontend JavaScript (API calls)
├── package.json
└── README.md

Installation

• Install dependencies:

npm install

Running the Server

Development mode (with auto-reload):

npm run dev

Production mode:

npm start

The server will start on http://localhost:3000

Using the Application

• Start the server:

  npm start
  # or for development with auto-reload:
  npm run dev
  

• Open your browser: Navigate to http://localhost:3000 to see the frontend interface.

• Try it out:

  • Add users using the form
  • Create posts
  • Click "Load All Users" or "Load All Posts" to fetch data from the backend
  • Check API status to verify backend connectivity

How Frontend and Backend Work Together

Frontend (public/app.js):

• Makes HTTP requests using fetch() API
• Sends data to backend via POST requests
• Receives data from backend via GET requests
• Updates the UI based on backend responses

Backend (server.js & routes/):

• Receives HTTP requests
• Processes data and stores in SQLite database
• Returns JSON responses
• Handles errors and validation

Example Flow:

• User fills out form in browser (frontend)
• JavaScript sends POST request to /api/v1/users (frontend → backend)
• Express server receives request, creates user (backend)
• Server returns JSON response with new user data (backend → frontend)
• JavaScript updates the page to show the new user (frontend)

API Endpoints

Base URL

• Development: http://localhost:3000

Version 1 (v1)

Users

• GET /api/v1/users - Get all users
• GET /api/v1/users/:id - Get user by ID
• POST /api/v1/users - Create a new user
• PUT /api/v1/users/:id - Update a user
• DELETE /api/v1/users/:id - Delete a user

Posts

• GET /api/v1/posts - Get all posts
• GET /api/v1/posts/:id - Get post by ID
• POST /api/v1/posts - Create a new post
• PUT /api/v1/posts/:id - Update a post
• DELETE /api/v1/posts/:id - Delete a post

Other

• GET / - API information
• GET /health - Health check endpoint
• GET /api/version - Get application version information

Example Requests

Create a User

curl -X POST http://localhost:3000/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "[e-mail]"}'

Get All Users

curl http://localhost:3000/api/v1/users

Create a Post

curl -X POST http://localhost:3000/api/v1/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "My Post", "content": "Post content", "authorId": 1}'

Adding New API Versions

To add a new version (e.g., v2):

• Create a new directory: routes/v2/
• Create route files similar to v1
• In server.js, add:

  const v2Routes = require('./routes/v2');
  app.use('/api/v2', v2Routes);
  

This allows you to maintain backward compatibility while introducing new features.

Database

This application uses SQLite for data persistence. The database file (data.db) is automatically created when you first run the server.

Database Schema

Users Table:

• id (INTEGER, PRIMARY KEY, AUTOINCREMENT)
• name (TEXT, NOT NULL)
• email (TEXT, NOT NULL, UNIQUE)
• created_at (DATETIME, DEFAULT CURRENT_TIMESTAMP)

Posts Table:

• id (INTEGER, PRIMARY KEY, AUTOINCREMENT)
• title (TEXT, NOT NULL)
• content (TEXT, NOT NULL)
• author_id (INTEGER, NOT NULL, FOREIGN KEY → users.id)
• created_at (DATETIME, DEFAULT CURRENT_TIMESTAMP)

Sample Data

When you first start the server, sample users and posts are automatically created if the database is empty.

Database File

• The database file data.db is created in the project root
• Data persists between server restarts
• The database file is excluded from git (see .gitignore)

Viewing the Database

You can use any SQLite browser tool to view the database:

• DB Browser for SQLite (GUI)
• Command line: sqlite3 data.db

Version Management

This application uses semantic-release for automated versioning based on Conventional Commits.

How It Works

Version is automatically determined from commit messages:

• feat: → Minor version bump (1.0.0 → 1.1.0)
• fix: → Patch version bump (1.0.0 → 1.0.1)
• feat!: or BREAKING CHANGE: → Major version bump (1.0.0 → 2.0.0)
• chore:, docs:, style: → No version bump

Viewing Version

In Frontend:

• The version information section shows current version, API version, build date, and Git information

Via API:

curl http://localhost:3000/api/version

Automated Releases

When you push commits to main branch with conventional commit messages:

• ✅ Analyzes commits and determines version bump
• ✅ Updates package.json version
• ✅ Updates CHANGELOG.md automatically
• ✅ Creates Git tag with new version
• ✅ Creates GitHub release with notes

Commit Message Examples

# Minor version bump (new feature)
git commit -m "feat: add user authentication"

# Patch version bump (bug fix)
git commit -m "fix: resolve database connection issue"

# Major version bump (breaking change)
git commit -m "feat!: remove deprecated API endpoint

BREAKING CHANGE: The /api/v1/old endpoint has been removed"

# No version bump (documentation)
git commit -m "docs: update README"

Setup

• Install dependencies (already done):

  npm install
  

• Add NPM_TOKEN to GitHub Secrets (if publishing to npm):

  • Go to GitHub repo → Settings → Secrets → Actions
  • Add NPM_TOKEN (generate in npm account)
  • GITHUB_TOKEN is automatically provided

• Start committing with conventional messages:

  git commit -m "feat: your new feature"
  git push origin main
  

See DOCUMENTATION.md for detailed versioning information.

Notes

• Data is now persisted in SQLite database and survives server restarts
• The database file is automatically created on first run
• Version information is automatically tracked and displayed
• Consider adding authentication and validation middleware for production use
• For high-traffic production apps, consider PostgreSQL or MySQL instead of SQLite