Reference Implementation

Relevant source files

Purpose and Scope

This page documents the Node.js reference implementation of the RealWorld API specification, located in apps/api/ This implementation serves as a production-ready example demonstrating best practices for building a compliant RealWorld backend. It implements all 15 endpoints defined in the OpenAPI specification using modern Node.js technologies.

For information about the API specification itself, see API Specification. For details on testing this implementation, see Testing Infrastructure. For build and deployment processes, see Build System & Workflows.

Sources: apps/api/package.json1-27 api/openapi.yml1-20

Overview

The reference implementation is a fully-functional API server built with Nitro (a server framework), Prisma ORM (for database access), and SQLite (for local development). It demonstrates proper implementation patterns including JWT-based authentication, input validation, error handling, and RESTful endpoint design.

Key Characteristics:

Aspect	Implementation
Location	`apps/api/` directory
Framework	Nitro (latest)
ORM	Prisma ^6.0.1
Database	SQLite (dev.db)
Authentication	JWT via jsonwebtoken ^9.0.2
Password Hashing	bcryptjs ^2.4.3
Validation	Postman collection compliance

Sources: apps/api/package.json1-27 apps/api/package-lock.json1-18

System Architecture

Diagram: Reference Implementation Component Architecture

This architecture separates concerns into three layers: HTTP routing (Nitro), business logic (route handlers with utilities), and data persistence (Prisma + SQLite).

Sources: apps/api/package.json1-27 apps/api/server/routes/api/articles/index.get.ts1-115

Technology Stack Overview

The implementation uses a carefully selected set of technologies:

Core Dependencies

Package	Version	Purpose
`@prisma/client`	^6.0.1	Type-safe database client
`bcryptjs`	^2.4.3	Password hashing
`slugify`	^1.6.0	URL-friendly article slugs

Development Dependencies

Package	Version	Purpose
`nitropack`	latest	Server framework & bundler
`prisma`	^6.0.1	Database toolkit
`jsonwebtoken`	^9.0.2	JWT generation/validation
`@ngneat/falso`	^5.0.0	Test data generation

For detailed information about each technology's role and configuration, see Technology Stack.

Sources: apps/api/package.json15-26

Request Processing Flow

Diagram: Request Processing Flow for GET /api/articles

This sequence demonstrates how an article listing request flows through the system, including optional authentication, query building, database operations, and response transformation.

Sources: apps/api/server/routes/api/articles/index.get.ts1-115

Project Structure

The reference implementation follows Nitro's file-system routing conventions:

apps/api/
├── package.json           # Dependencies and scripts
├── prisma/
│   ├── schema.prisma     # Database schema definition
│   ├── seed.ts           # Database seeding script
│   └── dev.db            # SQLite database file (generated)
├── server/
│   ├── routes/
│   │   └── api/          # All routes under /api prefix
│   │       ├── articles/
│   │       │   ├── index.get.ts              # GET /api/articles
│   │       │   ├── index.post.ts             # POST /api/articles
│   │       │   ├── feed.get.ts               # GET /api/articles/feed
│   │       │   └── [slug]/
│   │       │       ├── index.get.ts          # GET /api/articles/:slug
│   │       │       ├── index.put.ts          # PUT /api/articles/:slug
│   │       │       ├── index.delete.ts       # DELETE /api/articles/:slug
│   │       │       ├── comments/...          # Comment endpoints
│   │       │       └── favorite.*.ts         # Favorite endpoints
│   │       ├── profiles/...                   # Profile endpoints
│   │       ├── tags.get.ts                    # GET /api/tags
│   │       ├── user.*.ts                      # Current user endpoints
│   │       └── users/...                      # Auth endpoints
│   ├── utils/
│   │   ├── article.mapper.ts                  # Transform DB → API format
│   │   ├── user.mapper.ts                     # User transformations
│   │   └── ...
│   ├── auth-event-handler.ts                  # Authentication wrapper
│   └── middleware/...                         # Request middleware
└── .output/                                    # Build output (generated)

Nitro automatically maps file paths to HTTP routes. For example, server/routes/api/articles/[slug]/index.get.ts handles GET /api/articles/:slug.

Sources: apps/api/server/routes/api/articles/index.get.ts1-2

Route Handler Mapping

The route handlers directly implement the OpenAPI specification endpoints:

Diagram: OpenAPI Endpoints to Route Handler Mapping

Each OpenAPI endpoint has a corresponding route handler file following Nitro's file-system routing convention. For detailed implementation patterns, see Route Handler Implementation.

Sources: api/openapi.yml21-453 apps/api/server/routes/api/articles/index.get.ts1-2

Authentication Implementation Pattern

The implementation uses a custom definePrivateEventHandler wrapper to handle JWT authentication:

Diagram: JWT Authentication Flow via definePrivateEventHandler

The authentication wrapper provides consistent JWT validation across all protected endpoints. It makes user information available via the auth parameter when a valid token is present. For implementation details, see Authentication Implementation.

Sources: apps/api/server/routes/api/articles/index.get.ts2-4 apps/api/server/routes/api/articles/index.get.ts53

Database Schema and Prisma Models

The Prisma schema defines five core models that map to the OpenAPI data models:

Diagram: Database Schema Entity-Relationship Model

The schema uses Prisma's relation features to handle many-to-many relationships (favorites, follows, article tags) and one-to-many relationships (author → articles, article → comments). For complete schema details and client generation, see Database Layer & Prisma.

Sources: apps/api/package.json12-14

Example: Article Retrieval Implementation

The GET /api/articles endpoint demonstrates key implementation patterns:

Query Building Logic

apps/api/server/routes/api/articles/index.get.ts55-114 implements complex query building:

Authorization-aware filtering: Articles are filtered to show only those authored by the authenticated user or marked as demo: true apps/api/server/routes/api/articles/index.get.ts60-72
Optional filters: Supports tag, author, and favorited query parameters apps/api/server/routes/api/articles/index.get.ts74-111
Pagination: Implements offset and limit query parameters apps/api/server/routes/api/articles/index.get.ts22-23

Database Query with Relations

apps/api/server/routes/api/articles/index.get.ts14-47 demonstrates Prisma's relation loading:

prisma.article.findMany({
  omit: { body: true },           // Exclude full body in list view
  where: { AND: andQueries },
  orderBy: { createdAt: 'desc' },
  include: {
    tagList: { ... },              // Load related tags
    author: { ... },               // Load author profile
    favoritedBy: true,             // Load favorite relationships
    _count: {                      // Count favorites
      select: { favoritedBy: true }
    }
  }
})

Response Transformation

apps/api/server/routes/api/articles/index.get.ts50-52 maps database records to API format using articleMapper() utility, which transforms Prisma's nested relations into the flat JSON structure defined by the OpenAPI spec.

Sources: apps/api/server/routes/api/articles/index.get.ts1-115

NPM Scripts

The implementation provides several scripts for development and deployment:

Script	Command	Purpose
`dev`	`nitro dev`	Start development server with hot reload
`build`	`nitro build`	Build production bundle to `.output/`
`start`	`node .output/server/index.mjs`	Run production server
`preview`	`node .output/server/index.mjs`	Preview production build
`prepare`	`nitro prepare`	Generate Nitro type definitions
`db:generate`	`npx prisma generate`	Generate Prisma Client from schema
`db:seed`	`npx prisma db seed`	Populate database with sample data

The db:seed script is configured to run prisma/seed.ts using ts-node, which uses @ngneat/falso to generate realistic test data.

For complete setup and execution instructions, see Running Locally.

Sources: apps/api/package.json3-14

Validation via Postman Tests

The reference implementation is validated against api/Conduit.postman_collection.json This test suite contains comprehensive assertions that verify:

Response Structure: All required fields present in correct format api/Conduit.postman_collection.json23-31
Authentication Flow: Token generation, storage, and validation api/Conduit.postman_collection.json140-144
ISO 8601 Timestamps: Date fields match expected format api/Conduit.postman_collection.json373
Pagination Logic: articlesCount represents total count, not page size api/Conduit.postman_collection.json800-804
Relationship Integrity: Favorites, follows, and tags work correctly

The implementation passes all tests when run via:

For details on the testing infrastructure, see Testing Infrastructure.

Sources: api/Conduit.postman_collection.json1-34 api/README.md1-12

Integration with Build System

The reference implementation is integrated into the repository's Makefile-based build system with targets such as:

make reference-implementation-setup - Install dependencies and prepare environment
make reference-implementation-dev - Start development server
make reference-implementation-test-with-postman - Run validation tests

These targets orchestrate multiple steps including Prisma client generation, database setup, server startup, and test execution. For complete build system documentation, see Build System & Workflows.

Sources: api/README.md4-11

Reference Implementation

Relevant source files

Purpose and Scope

Sources: apps/api/package.json1-27 api/openapi.yml1-20

Overview

Key Characteristics:

Aspect	Implementation
Location	`apps/api/` directory
Framework	Nitro (latest)
ORM	Prisma ^6.0.1
Database	SQLite (dev.db)
Authentication	JWT via jsonwebtoken ^9.0.2
Password Hashing	bcryptjs ^2.4.3
Validation	Postman collection compliance

Sources: apps/api/package.json1-27 apps/api/package-lock.json1-18

System Architecture

Diagram: Reference Implementation Component Architecture

This architecture separates concerns into three layers: HTTP routing (Nitro), business logic (route handlers with utilities), and data persistence (Prisma + SQLite).

Sources: apps/api/package.json1-27 apps/api/server/routes/api/articles/index.get.ts1-115

Technology Stack Overview

The implementation uses a carefully selected set of technologies:

Core Dependencies

Package	Version	Purpose
`@prisma/client`	^6.0.1	Type-safe database client
`bcryptjs`	^2.4.3	Password hashing
`slugify`	^1.6.0	URL-friendly article slugs

Development Dependencies

Package	Version	Purpose
`nitropack`	latest	Server framework & bundler
`prisma`	^6.0.1	Database toolkit
`jsonwebtoken`	^9.0.2	JWT generation/validation
`@ngneat/falso`	^5.0.0	Test data generation

For detailed information about each technology's role and configuration, see Technology Stack.

Sources: apps/api/package.json15-26

Request Processing Flow

Diagram: Request Processing Flow for GET /api/articles

This sequence demonstrates how an article listing request flows through the system, including optional authentication, query building, database operations, and response transformation.

Sources: apps/api/server/routes/api/articles/index.get.ts1-115

Project Structure

The reference implementation follows Nitro's file-system routing conventions:

apps/api/
├── package.json           # Dependencies and scripts
├── prisma/
│   ├── schema.prisma     # Database schema definition
│   ├── seed.ts           # Database seeding script
│   └── dev.db            # SQLite database file (generated)
├── server/
│   ├── routes/
│   │   └── api/          # All routes under /api prefix
│   │       ├── articles/
│   │       │   ├── index.get.ts              # GET /api/articles
│   │       │   ├── index.post.ts             # POST /api/articles
│   │       │   ├── feed.get.ts               # GET /api/articles/feed
│   │       │   └── [slug]/
│   │       │       ├── index.get.ts          # GET /api/articles/:slug
│   │       │       ├── index.put.ts          # PUT /api/articles/:slug
│   │       │       ├── index.delete.ts       # DELETE /api/articles/:slug
│   │       │       ├── comments/...          # Comment endpoints
│   │       │       └── favorite.*.ts         # Favorite endpoints
│   │       ├── profiles/...                   # Profile endpoints
│   │       ├── tags.get.ts                    # GET /api/tags
│   │       ├── user.*.ts                      # Current user endpoints
│   │       └── users/...                      # Auth endpoints
│   ├── utils/
│   │   ├── article.mapper.ts                  # Transform DB → API format
│   │   ├── user.mapper.ts                     # User transformations
│   │   └── ...
│   ├── auth-event-handler.ts                  # Authentication wrapper
│   └── middleware/...                         # Request middleware
└── .output/                                    # Build output (generated)

Nitro automatically maps file paths to HTTP routes. For example, server/routes/api/articles/[slug]/index.get.ts handles GET /api/articles/:slug.

Sources: apps/api/server/routes/api/articles/index.get.ts1-2

Route Handler Mapping

The route handlers directly implement the OpenAPI specification endpoints:

Diagram: OpenAPI Endpoints to Route Handler Mapping

Each OpenAPI endpoint has a corresponding route handler file following Nitro's file-system routing convention. For detailed implementation patterns, see Route Handler Implementation.

Sources: api/openapi.yml21-453 apps/api/server/routes/api/articles/index.get.ts1-2

Authentication Implementation Pattern

The implementation uses a custom definePrivateEventHandler wrapper to handle JWT authentication:

Diagram: JWT Authentication Flow via definePrivateEventHandler

Sources: apps/api/server/routes/api/articles/index.get.ts2-4 apps/api/server/routes/api/articles/index.get.ts53

Database Schema and Prisma Models

The Prisma schema defines five core models that map to the OpenAPI data models:

Diagram: Database Schema Entity-Relationship Model

Sources: apps/api/package.json12-14

Example: Article Retrieval Implementation

The GET /api/articles endpoint demonstrates key implementation patterns:

Query Building Logic

apps/api/server/routes/api/articles/index.get.ts55-114 implements complex query building:

Authorization-aware filtering: Articles are filtered to show only those authored by the authenticated user or marked as demo: true apps/api/server/routes/api/articles/index.get.ts60-72
Optional filters: Supports tag, author, and favorited query parameters apps/api/server/routes/api/articles/index.get.ts74-111
Pagination: Implements offset and limit query parameters apps/api/server/routes/api/articles/index.get.ts22-23

Database Query with Relations

apps/api/server/routes/api/articles/index.get.ts14-47 demonstrates Prisma's relation loading:

prisma.article.findMany({
  omit: { body: true },           // Exclude full body in list view
  where: { AND: andQueries },
  orderBy: { createdAt: 'desc' },
  include: {
    tagList: { ... },              // Load related tags
    author: { ... },               // Load author profile
    favoritedBy: true,             // Load favorite relationships
    _count: {                      // Count favorites
      select: { favoritedBy: true }
    }
  }
})

Response Transformation

Sources: apps/api/server/routes/api/articles/index.get.ts1-115

NPM Scripts

The implementation provides several scripts for development and deployment:

Script	Command	Purpose
`dev`	`nitro dev`	Start development server with hot reload
`build`	`nitro build`	Build production bundle to `.output/`
`start`	`node .output/server/index.mjs`	Run production server
`preview`	`node .output/server/index.mjs`	Preview production build
`prepare`	`nitro prepare`	Generate Nitro type definitions
`db:generate`	`npx prisma generate`	Generate Prisma Client from schema
`db:seed`	`npx prisma db seed`	Populate database with sample data

The db:seed script is configured to run prisma/seed.ts using ts-node, which uses @ngneat/falso to generate realistic test data.

For complete setup and execution instructions, see Running Locally.

Sources: apps/api/package.json3-14

Validation via Postman Tests

The reference implementation is validated against api/Conduit.postman_collection.json This test suite contains comprehensive assertions that verify:

Response Structure: All required fields present in correct format api/Conduit.postman_collection.json23-31
Authentication Flow: Token generation, storage, and validation api/Conduit.postman_collection.json140-144
ISO 8601 Timestamps: Date fields match expected format api/Conduit.postman_collection.json373
Pagination Logic: articlesCount represents total count, not page size api/Conduit.postman_collection.json800-804
Relationship Integrity: Favorites, follows, and tags work correctly

The implementation passes all tests when run via:

For details on the testing infrastructure, see Testing Infrastructure.

Sources: api/Conduit.postman_collection.json1-34 api/README.md1-12

Integration with Build System

The reference implementation is integrated into the repository's Makefile-based build system with targets such as:

make reference-implementation-setup - Install dependencies and prepare environment
make reference-implementation-dev - Start development server
make reference-implementation-test-with-postman - Run validation tests

These targets orchestrate multiple steps including Prisma client generation, database setup, server startup, and test execution. For complete build system documentation, see Build System & Workflows.

Sources: api/README.md4-11

Reference Implementation

Purpose and Scope

Overview

System Architecture

Technology Stack Overview

Core Dependencies

Development Dependencies

Request Processing Flow

Project Structure

Route Handler Mapping

Authentication Implementation Pattern

Database Schema and Prisma Models

Example: Article Retrieval Implementation

Query Building Logic

Database Query with Relations

Response Transformation

NPM Scripts

Validation via Postman Tests

Integration with Build System

On this page

Reference Implementation

Purpose and Scope

Overview

System Architecture

Technology Stack Overview

Core Dependencies

Development Dependencies

Request Processing Flow

Project Structure

Route Handler Mapping

Authentication Implementation Pattern

Database Schema and Prisma Models

Example: Article Retrieval Implementation

Query Building Logic

Database Query with Relations

Response Transformation

NPM Scripts

Validation via Postman Tests

Integration with Build System

On this page