API Design and Data Flow

Now we are at the point where we connect the frontend (what users see) with the backend (where all the logic lives).

This is the bridge of your platform – the API layer that makes everything communicate smoothly.

“APIs are the languages your systems speak to each other – design them like you would write for humans, not machines.”

The Substack-like platform is an ecosystem:

• Creators write and publish posts.
• Readers subscribe and consume.
• Payments, analytics, and emails operate behind the scenes.

The API layer makes these experiences possible – consistent, secure, and structured.

What is an API in This Context?

An API (Application Programming Interface) is a set of endpoints that:

• Accept requests from the frontend,
• Perform logic in the backend,
• Return responses (data, success, or error).

We will design our APIs using:

• REST architecture (simple and widely supported)
• JSON as the data exchange format
• HTTP verbs to define intent:
  • GET -> fetch, POST -> create, PUT -> update, DELETE -> remove

API Layer Overview

The main API modules:

High-Level Data Flow Diagram

     ┌────────────────────┐
     │     Frontend       │
     │ (Next.js + React)  │
     └───────┬────────────┘
             │  HTTPS JSON
             ▼
     ┌────────────────────┐
     │     API Gateway    │
     │ (Express/NestJS)   │
     └───────┬────────────┘
             │
  ┌───────────┼───────────────────┐
  ▼           ▼                   ▼
Auth API   Post API         Subscription API
  │           │                     │
  ▼           ▼                     ▼
PostgreSQL  PostgreSQL           Stripe / DB
   │            │                     │
   ▼            ▼                     ▼
 Redis Cache  Email Queue          Analytics

This shows a clean modular flow – each service does one job, and they interact through APIs and queues.

Authentication APIs

1 POST /api/auth/register

Purpose: Create a new user.

Request:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "strongpassword"
}

Response:

{
  "status": "success",
  "message": "User registered successfully."
}

2 POST /api/auth/login

Purpose: Authenticate user and issue JWT token.

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "user": {
    "id": "uuid",
    "role": "creator"
  }
}

User Profile APIs

GET /api/users/:id

Returns pubic user info.

Response:

{
  "id": "uuid",
  "name": "John Doe",
  "bio": "Tech writer & creator",
  "followers_count": 1220
}

PUT /api/users/:id

Update profile info.

Post APIs

1 POST /api/posts

Purpose: Create a new post (draft or published).

Request:

{
  "title": "The Future of Creator Economy",
  "content": "<p>Long form content...</p>",
  "visibility": "public"
}

Response:

{
  "id": "uuid",
  "status": "draft",
  "created_at": "2025-10-25T10:30:00Z"
}

2 GET /api/posts/:slug

Fetch post by slug for readers.

Response:

{
  "title": "The Future of Creator Economy",
  "author": "John Doe",
  "content": "<p>...</p>",
  "published_at": "2025-10-20T18:00:00Z"
}

3 PUT /api/posts/:id

Update a post (edit title/content)

4 DELETE /api/posts/:id

Delete a post.

Subscription APIs

1 POST /api/subscriptions

Purpose: Subscribe a reader to a creator.

Request:

{
  "creator_id": "uuid",
  "plan_type": "free"
}

Response:

{
  "message": "Subscribed successfully",
  "subscription_id": "uuid"
}

2 DELETE /api/subscriptions/:id

Unsubscribe.

Payment APIs

1 POST /api/payments/checkout

Creates a Stripe Checkout session.

Request:

{
  "creator_id": "uuid",
  "amount": 5,
  "currency": "USD"
}

Response:

{
  "checkout_url": "https://checkout.stripe.com/session/..."
}

2 POST /api/payments/webhook

Stripe sends payment confirmation events here.

Backend Flow:

1. Verify event signature.
2. Update subscription status to active.
3. Send payment confirmation email.

Email APIs

1 POST /api/emails/send

Trigger newsletter after publishing a post.

Flow:

• Create entry in EmailQueue table.
• Worker service (cron job) sends emails via SendGrid.
• Update status to “sent/failed”.

Analytics APIs

GET /api/analytics/post/:id

Returns post-level stats.

Response:

{
  "views": 1200,
  "clicks": 340,
  "email_opens": 620
}

POST /api/analytics/track

Frontend triggers this when a user views or clicks a post.