I recently built a temporary message-sharing API from scratch using NestJS, PostgreSQL, Prisma and Redis.
The idea is simple:
Create a message, generate a short code, share it, and let the message automatically expire.
But while building it, I wanted to go beyond a basic CRUD API and understand how things like validation, password protection, visit limits, atomic database updates, caching, TTLs, cleanup jobs, rate limiting and API documentation actually fit together.
This post walks through the architecture and the problems each piece solves.
🚀 What did I build?
The API allows users to create temporary messages with configurable rules:
- Maximum message length:
100 characters - Expiration:
1 hour,1 day, or7 days - Maximum number of visits
- Optional password protection
- Optional one-time access
- Automatic expiration
- Redis caching
- Rate limiting
- Swagger API documentation
- No authentication or user accounts
The basic flow looks like this:
Client
│
▼
NestJS Controller
│
▼
DTO Validation
│
▼
LinksService
│
├──────────────► Redis
│
▼
Prisma
│
▼
PostgreSQL
🛠️ Tech Stack
The project uses:
| Technology | Purpose |
|---|---|
| NestJS | Backend framework |
| TypeScript | Programming language |
| PostgreSQL | Persistent database |
| Prisma | ORM |
| Redis | Caching |
| Memurai | Redis-compatible server on Windows |
| bcrypt | Password hashing |
| Swagger | API documentation |
| class-validator | DTO validation |
| @nestjs/schedule | Cleanup cron jobs |
| @nestjs/throttler | Rate limiting |
📁 Project Structure
The project is organized into modules instead of putting everything into one large file.
src/
├── links/
│ ├── dto/
│ │ ├── create-link.dto.ts
│ │ └── access-link.dto.ts
│ ├── links.controller.ts
│ ├── links.service.ts
│ └── links.module.ts
│
├── prisma/
│ ├── prisma.service.ts
│ └── prisma.module.ts
│
├── redis/
│ ├── redis.service.ts
│ └── redis.module.ts
│
├── app.module.ts
└── main.ts
I kept the project intentionally small so that each layer had a clear responsibility.
1. Creating a Temporary Message
The first endpoint is:
POST /links
A request looks like:
{
"message": "Hello, this message will expire!",
"expiresIn": 3600,
"maxVisits": 5,
"password": "secret123",
"oneTime": false
}
The server generates:
shortCode
expiresAt
The response is:
{
"code": "6639befd",
"expiresAt": "2026-09-19T15:30:00.000Z"
}
The client can then share:
/link/6639befd
2. DTO Validation
One of the first things I learned was that validation should happen at the API boundary.
Instead of manually checking every property inside the service, NestJS can validate the incoming request using DTOs.
For example:
export class CreateLinkDto {
@IsString()
@MinLength(1)
@MaxLength(100)
message: string;
@IsInt()
@Min(60)
@Max(604800)
expiresIn: number;
@IsOptional()
@IsInt()
@Min(1)
maxVisits?: number;
@IsOptional()
@IsString()
@MinLength(4)
password?: string;
@IsOptional()
@IsBoolean()
oneTime?: boolean;
}
This means the API rejects invalid data before it reaches the business logic.
For example:
{
"message": "",
"expiresIn": 10
}
will fail validation because:
message.length >= 1
expiresIn >= 60
The global validation pipe is configured like this:
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
transform: true,
}),
);
The whitelist option also prevents unexpected properties from being accepted.
3. Calculating Expiration
The client sends the duration in seconds.
For example:
3600 seconds = 1 hour
The server converts it into an actual expiration timestamp:
const expiresAt = new Date(
Date.now() + createLinkDto.expiresIn * 1000,
);
So instead of storing:
expiresIn = 3600
the database stores:
expiresAt = 2026-09-19T15:30:00Z
This makes expiration checks straightforward:
if (link.expiresAt <= new Date()) {
throw new GoneException('Link has expired');
}
4. PostgreSQL Database
The persistent data is stored in PostgreSQL.
The core model looks like this:
model link {
code String @unique
createdAt DateTime @default(now()) @db.Timestamptz(6)
expiresAt DateTime @db.Timestamptz(6)
id String @id @db.Uuid
maxVisits Int?
message String @db.VarChar(100)
oneTime Boolean @default(false)
passwordHash String?
updatedAt DateTime @db.Timestamptz(6)
used Boolean @default(false)
visitCount Int @default(0)
@@index([expiresAt])
}
There are a few important fields here.
expiresAt
Determines when the message expires.
maxVisits
Optional maximum number of successful accesses.
visitCount
Tracks successful accesses.
oneTime
Determines whether the message can only be accessed once.
used
Tracks whether a one-time message has already been consumed.
passwordHash
Stores the hashed password rather than the original password.
5. Password Protection
I didn't want passwords to be stored as plain text.
Instead, the password is hashed using bcrypt.
const passwordHash = createLinkDto.password
? await bcrypt.hash(createLinkDto.password, 10)
: null;
The database therefore contains something like:
$2b$10$.....................................................
instead of:
secret123
When someone accesses a protected message, the supplied password is compared against the hash:
const isPasswordValid = await bcrypt.compare(
password,
link.passwordHash,
);
If the password is incorrect:
throw new UnauthorizedException(
'Invalid password',
);
6. Public vs Protected Messages
There are two access flows.
Public message
GET /links/:shortCode
Example:
GET /links/6639befd
If the message isn't password protected, the API directly returns:
{
"message": "Hello!"
}
Protected message
The frontend first calls:
GET /links/6639befd
The API responds:
401 Unauthorized
The frontend can then display a password input.
After the user enters the password:
POST /links/6639befd/access
with:
{
"password": "secret123"
}
The shared URL remains:
/link/6639befd
The /access endpoint is only an API endpoint used by the frontend.
7. Maximum Visit Limit
One interesting part of the project was implementing maximum visits correctly.
Suppose a message has:
{
"maxVisits": 2
}
We want:
Request 1 → 200
Request 2 → 200
Request 3 → 410
A naive implementation would be:
if (link.visitCount >= link.maxVisits) {
throw new GoneException();
}
await prisma.link.update({
data: {
visitCount: {
increment: 1,
},
},
});
But this has a concurrency problem.
Imagine two requests arrive at almost exactly the same time:
Request A → visitCount = 1
Request B → visitCount = 1
Both could pass the check before either increments the counter.
That could allow more accesses than intended.
8. Atomic Access Claim
Instead, I used a conditional database update.
const result = await this.prisma.link.updateMany({
where: {
id: link.id,
AND: [
{
OR: [
{
maxVisits: null,
},
{
maxVisits: {
gt: link.visitCount,
},
},
],
},
],
},
data: {
visitCount: {
increment: 1,
},
},
});
Then:
if (result.count === 0) {
throw new GoneException(
'Link has reached its maximum visits',
);
}
The important idea is:
Don't separate "check" and "update" when the correctness of the operation depends on both happening together.
The database becomes responsible for atomically claiming the access.
9. One-Time Messages
The same idea is used for one-time messages.
For a one-time message:
{
"oneTime": true
}
the first successful access should work:
First request → 200
Second request → 410
The database update includes:
used: false
as part of the condition.
Then the successful update sets:
used: true
The important part is that checking and consuming the message happen as one database operation.
10. Adding Redis
After the core PostgreSQL implementation was working, I added Redis.
The purpose wasn't simply:
"I need Redis because real projects use Redis."
Instead, I wanted to solve a specific problem:
Repeatedly reading frequently accessed temporary messages from PostgreSQL isn't necessary when the message itself can be cached.
The flow becomes:
Client
│
▼
NestJS
│
▼
Redis
│
├── HIT ──────► Return message
│
└── MISS
│
▼
PostgreSQL
11. Redis TTL
The nice part about temporary data is that Redis already supports expiration.
When creating a cache entry:
await this.redis.setWithExpiry(
`link:${link.code}`,
link.message,
createLinkDto.expiresIn,
);
The Redis operation uses:
EX = expiration time in seconds
So if the message expires in one hour:
TTL = 3600
Redis automatically removes the key when the TTL reaches zero.
I tested it using:
memurai-cli
and:
KEYS link:*
which returned:
1) "link:6639befd"
Then:
GET link:6639befd
returned:
"Redis test message"
And:
TTL link:6639befd
returned something like:
(integer) 3531
12. Why Not Cache Everything?
This was an important design decision.
Messages with these features cannot simply be treated as immutable cached values:
maxVisits
oneTime
password protection
because access requires additional state and validation.
So I only cache messages that are safe to serve directly:
private isCacheable(link: {
passwordHash: string | null;
maxVisits: number | null;
oneTime: boolean;
}) {
return (
!link.passwordHash &&
link.maxVisits === null &&
!link.oneTime
);
}
In other words:
Simple public message
↓
Redis
↓
fast access
while:
Password protected
OR
Maximum visits
OR
One-time
↓
PostgreSQL
↓
validation + atomic access
This keeps Redis from bypassing access-control logic.
13. Automatic Cleanup
Redis handles its own TTL, but PostgreSQL still contains expired records.
So I added a scheduled cleanup job using:
@nestjs/schedule
The job runs every hour:
@Cron('0 * * * *')
async cleanupExpiredLinks() {
const result = await this.prisma.link.deleteMany({
where: {
expiresAt: {
lt: new Date(),
},
},
});
if (result.count > 0) {
this.logger.log(
`Deleted ${result.count} expired link(s)`,
);
}
}
This keeps the PostgreSQL table from growing indefinitely.
The architecture is therefore:
PostgreSQL
│
└── Cleanup job
│
└── Delete expired records
Redis
│
└── TTL
│
└── Automatically remove expired cache
14. Rate Limiting
Since this is a public API, unrestricted requests could become a problem.
I added NestJS throttling:
ThrottlerModule.forRoot([
{
ttl: 60_000,
limit: 60,
},
])
This allows roughly:
60 requests
per 60 seconds
per client according to the throttler's request-tracking behavior.
The guard is registered globally:
providers: [
{
provide: APP_GUARD,
useClass: ThrottlerGuard,
},
],
This is a simple first layer of protection against accidental or abusive request bursts.
15. Swagger Documentation
I also added Swagger because an API shouldn't require someone to read the source code to understand how to use it.
Swagger is available at:
/api/docs
The application is configured with:
const config = new DocumentBuilder()
.setTitle('Link Expiry API')
.setDescription('Temporary message sharing API')
.setVersion('1.0')
.build();
const document = SwaggerModule.createDocument(
app,
config,
);
SwaggerModule.setup(
'api/docs',
app,
document,
);
DTO properties are also documented:
@ApiProperty({
description: 'Temporary message to store',
example: 'Hello, this message will expire!',
minLength: 1,
maxLength: 100,
})
This makes the API much easier to explore and test.
🔌 API Endpoints
The API currently exposes three main endpoints.
Create a message
POST /links
Example:
{
"message": "Hello from my API!",
"expiresIn": 3600
}
Response:
{
"code": "6639befd",
"expiresAt": "2026-09-19T15:30:00.000Z"
}
Access a message
GET /links/:shortCode
Example:
GET /links/6639befd
Response:
{
"message": "Hello from my API!"
}
Access a protected message
POST /links/:shortCode/access
Request:
{
"password": "secret123"
}
Response:
{
"message": "This is a protected message."
}
⚠️ HTTP Status Codes
I also wanted the API behavior to be explicit.
| Status | Meaning |
|---|---|
200 |
Message successfully retrieved |
201 |
Message successfully created |
400 |
Invalid request |
401 |
Password required or incorrect |
404 |
Message doesn't exist |
410 |
Message expired or can no longer be accessed |
Using 410 Gone for expired messages felt appropriate because the resource existed but is no longer available.
🧪 Manual Testing
I decided to manually test the API rather than immediately building a large automated test suite.
Some of the scenarios tested were:
✓ Create public message
✓ Create password-protected message
✓ Correct password
✓ Incorrect password
✓ Expired message
✓ Maximum visit limit
✓ One-time message
✓ Redis cache hit
✓ Redis TTL
✓ PostgreSQL fallback
✓ Rate limiting
✓ Swagger documentation
✓ Expired-record cleanup
For example:
Invoke-RestMethod `
http://localhost:3000/links/6639befd
returned:
message
-------
Redis test message
showing that the cached message could be served through the API.
🧠 What I Learned
The biggest value of this project wasn't the final API.
It was understanding why each component exists.
NestJS
I learned how controllers, services, modules, DTOs and dependency injection fit together.
DTO Validation
I learned that validating input at the API boundary makes business logic much cleaner.
PostgreSQL
I learned how persistent application state differs from temporary cached state.
Prisma
I learned how an ORM interacts with the database and how conditional updates can help with concurrency.
bcrypt
I learned why passwords should never be stored directly.
Redis
I learned that caching isn't simply:
"Put everything in Redis."
Instead, you need to decide:
What can safely be cached?
What state must remain authoritative?
When should the cache expire?
Atomic Operations
This was probably one of the most useful concepts from the project.
Instead of:
Check
↓
Update
sometimes you need:
Conditional Update
↓
Success/Failure
so concurrent requests can't bypass your business rule.
Cron Jobs
I also learned that expiration in an application doesn't automatically mean the database cleans itself up.
🏗️ Current Architecture
The final architecture looks roughly like this:
┌───────────────┐
│ Client │
└───────┬───────┘
│
▼
┌───────────────┐
│ NestJS API │
└───────┬───────┘
│
┌───────▼───────┐
│ Validation │
│ + Throttling │
└───────┬───────┘
│
▼
┌───────────────┐
│ LinksService │
└───────┬───────┘
│
┌───────────┴───────────┐
│ │
▼ ▼
┌──────────────┐ ┌────────────────┐
│ Redis │ │ PostgreSQL │
│ │ │ │
│ Cached │ │ Source of │
│ messages │ │ truth │
│ │ │ │
│ TTL │ │ Visit limits │
└──────────────┘ │ One-time state │
│ Password hash │
└────────────────┘
│
▼
┌──────────────┐
│ Cron Cleanup │
└──────────────┘
📦 Running the Project
Install dependencies:
npm install
Start PostgreSQL and Redis/Memurai.
Then configure:
DATABASE_URL="postgresql://postgres:YOUR_PASSWORD@localhost:5432/link_expiry"
REDIS_URL="redis://localhost:6379"
Generate Prisma Client:
npx prisma generate
Validate the Prisma schema:
npx prisma validate
Start NestJS:
npm run start:dev
The API will be available at:
http://localhost:3000
Swagger:
http://localhost:3000/api/docs
🔮 What Could Come Next?
There are several directions this project could evolve in.
For example:
Authentication
Analytics
Custom expiration
Frontend UI
Admin dashboard
Distributed rate limiting
Redis-based counters
Background workers
Docker deployment
Observability
Metrics
Horizontal scaling
But I intentionally didn't add everything at once.
The goal was to understand the fundamentals first and then introduce infrastructure only when there was a reason for it.
💭 Final Thoughts
What started as a simple:
"Create a message → give me a link → expire it"
turned into a surprisingly good backend learning project.
The interesting part wasn't creating the endpoint.
It was figuring out questions like:
What happens when two users access the message simultaneously?
Where should expiration be enforced?
Should every message be cached?
What happens to expired database records?
How should passwords be stored?
How do we prevent unlimited requests?
How do we make the API easy for others to understand?
Those questions pushed the project beyond a basic CRUD API and helped me understand several backend concepts that I had previously only seen in theory.
🚀 Tech Stack
NestJS
TypeScript
PostgreSQL
Prisma
Redis
Memurai
bcrypt
Swagger
class-validator
@nestjs/schedule
@nestjs/throttler
If you're also learning backend development, I'd highly recommend building something small and then adding complexity only when you can explain why you need it.
That's what made this project much more useful for me than simply following a tutorial.
📌 Source Code
The complete project is available on GitHub:
If you find the project useful or have suggestions for improving the architecture, I'd love to hear your feedback.
👨💻 About the Project
Built as a hands-on learning project to understand:
NestJS
↓
API Design
↓
Validation
↓
PostgreSQL
↓
Prisma
↓
Concurrency
↓
Redis
↓
Caching + TTL
↓
Background Cleanup
↓
Rate Limiting
Tags: #nestjs #typescript #postgresql #prisma #redis #backend #webdevelopment #javascript
Top comments (0)