Skip to content

README.md

Latest commit

 

History

History
131 lines (99 loc) · 3.56 KB

README.md

File metadata and controls

131 lines (99 loc) · 3.56 KB

basic-rest-api

A personal REST API playground built to practice and maintain knowledge on backend best practices — clean architecture, proper error handling, validation, and TypeScript tooling.

Tech Stack

  • Runtime — Node.js (version managed via .nvmrc)
  • Framework — Hono
  • Language — TypeScript
  • Package Manager — pnpm (workspace setup)
  • Linting — ESLint
  • Formatting — Prettier

Project Structure

src
├── api/
│   └── v1/
│       ├── endpoints/       # Route handlers per resource (authors, books)
│       ├── responses/       # Typed HTTP response shapes (e.g. error response)
│       └── router.ts        # v1 router composition
├── core/
│   ├── data/                # JSON data files (authors.json, books.json)
│   └── index.ts             # Core bootstrapping
├── domain/                  # Business logic — no external dependencies
│   ├── errors/              # Typed error interfaces
│   ├── models/              # Domain entities (Author, Book)
│   └── services/            # Business logic per resource
├── middleware/
│   └── error-handler.ts     # Global error handling middleware
├── routes/
│   └── index.ts             # Top-level route registration
├── utils/
│   └── logger.util.ts       # Logging utility
├── validations/
│   └── id.schema.ts         # Shared input validation schemas
└── index.ts                 # App entry point

The project follows Clean Architecture principles — dependencies always point inward. The domain/ layer has zero knowledge of Hono, JSON files, or any infrastructure concern.

Getting Started

Prerequisites: Node.js (see .nvmrc), pnpm

# Install dependencies
pnpm install

# Start development server (with hot reload)
pnpm dev

# Build
pnpm build

# Start production server
pnpm start

Testing

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

Code Quality

# Check formatting
pnpm format:check

# Fix formatting
pnpm format

# Check linting
pnpm lint:check

# Fix linting
pnpm lint

API Endpoints

Authors

Method Endpoint Description
GET /authors Get all authors
GET /authors/:id Get author by ID
POST /authors Create a new author
PUT /authors/:id Update an author
DELETE /authors/:id Delete an author

Books

Method Endpoint Description
GET /books Get all books
GET /books/:id Get book by ID
POST /books Create a new book
PUT /books/:id Update a book
DELETE /books/:id Delete a book

Error Handling

All errors follow a consistent typed structure:

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "Author with id '42' was not found.",
  "status": 404
}

Specialised error types include ValidationError, AuthenticationError, AuthorizationError, ResourceNotFoundError, RateLimitError, ConflictError, and ServerError.

Goals & Practices

This repo is used to explore and solidify:

  • Clean Architecture & separation of concerns
  • Typed error handling in TypeScript
  • Input validation patterns
  • REST API design conventions
  • Tooling setup (ESLint, Prettier, pnpm workspaces, tsconfig)