DEV Community: Stack Horizon

REST vs GraphQL in Practice

Stack Horizon — Tue, 04 Aug 2026 00:01:06 +0000

The Practical Differences

When I started building APIs, REST was the default. Then GraphQL came along and promised to fix everything. After using both in real projects, I've learned that the choice isn't about which is 'better' but about what fits your use case. Let's break down the practical differences.

REST: Simple and Predictable

REST is built around resources and HTTP methods. You have endpoints like /users and /users/1. Each endpoint returns a fixed shape. It's easy to understand, cache, and debug.

Here's a typical REST call:

// Get user and their posts
const userRes = await fetch('/users/1');
const user = await userRes.json();
const postsRes = await fetch('/users/1/posts');
const posts = await postsRes.json();

Pros:

Simple to implement and consume
Built-in caching with HTTP
Great for public APIs where you control the response shape
Easy to version (/v1/users)

Cons:

Over-fetching: you get all fields even if you need one
Under-fetching: you need multiple requests to get related data
No way for the client to request exactly what it needs

GraphQL: Flexible but Complex

GraphQL gives the client control over the response. You send a query and get exactly what you ask for.

query {
  user(id: 1) {
    name
    posts {
      title
    }
  }
}

One request gets the user and their posts, with only the fields you need.

Pros:

No over-fetching or under-fetching
Single round-trip for complex data
Strongly typed schema with introspection
Great for mobile apps where bandwidth matters

Cons:

More complex to set up and maintain
Caching is harder (no natural HTTP caching)
Potential for expensive queries if not careful
Requires a learning curve for clients

Real-World Considerations

1. Team Experience

If your team knows REST well, introducing GraphQL adds a lot of new concepts: resolvers, schema, fragments, mutations. For a small internal API, REST is often easier.

2. Client Needs

If your clients are mostly web apps with simple data needs, REST is fine. If you have mobile clients with variable network conditions, GraphQL's ability to fetch exactly what's needed is a big win.

3. Performance

REST can be faster for simple requests because of HTTP caching and CDN support. GraphQL can be slower if you have deeply nested queries, but you can mitigate with query complexity limits and DataLoader for batching.

4. Tooling

REST has mature tooling: Swagger, Postman, caching proxies. GraphQL has excellent tools like Apollo and GraphiQL, but they are more complex to set up.

A Hybrid Approach

You don't have to choose one. Many projects start with REST and add GraphQL for specific use cases. For example, you can expose a REST API for public consumption and a GraphQL API for your own frontend. This gives you the best of both worlds.

My Take

For my current project, I used REST for the public API because it's stable and easy for third parties to consume. Internally, the frontend uses GraphQL to avoid multiple round-trips. It adds some complexity, but the improved developer experience is worth it.

If you're starting fresh and your API is mostly for your own clients, GraphQL is a solid choice. If you're building a public API with unknown consumers, REST is safer.

Bottom Line

REST is like a buffet: you get a fixed plate. GraphQL is like ordering à la carte: you pick exactly what you want. Both work, but they fit different situations. Understand your requirements, your team, and your clients before choosing.

Happy coding!

JWT Auth Without the Confusion

Stack Horizon — Fri, 31 Jul 2026 00:00:57 +0000

What JWT Actually Is

JWT (JSON Web Token) is a compact, URL-safe way to transmit claims between two parties. It's not a magic security solution. It's a token format: three base64url-encoded segments separated by dots (header.payload.signature).

header: {"alg":"HS256","typ":"JWT"}
payload: {"sub":"user123","iat":1700000000}
signature: HMACSHA256(base64url(header)+"."+base64url(payload), secret)

The Common Mistake: Storing JWT in localStorage

Don't do it. localStorage is accessible via JavaScript (XSS). If an attacker injects a script, they steal your tokens. Use httpOnly cookies instead. The cookie is sent automatically with requests and is not readable by JS.

// Bad: vulnerable to XSS
localStorage.setItem('token', jwt);

// Better: httpOnly cookie (set by server)
Set-Cookie: token=<jwt>; HttpOnly; Secure; SameSite=Strict

How to Implement JWT Auth (The Practical Way)

1. Login endpoint issues a JWT in a cookie

app.post('/login', (req, res) => {
  const { username, password } = req.body;
  const user = authenticate(username, password);
  if (!user) return res.status(401).send('Invalid credentials');

  const token = jwt.sign(
    { sub: user.id, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '15m' }
  );

  res.cookie('token', token, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 15 * 60 * 1000
  });
  res.json({ message: 'Logged in' });
});

2. Middleware verifies the token on each request

function authMiddleware(req, res, next) {
  const token = req.cookies.token;
  if (!token) return res.status(401).send('No token');

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(403).send('Invalid token');
  }
}

app.get('/protected', authMiddleware, (req, res) => {
  res.json({ user: req.user });
});

3. Refresh tokens for longer sessions

Access tokens are short-lived (15 min). Use a refresh token (long-lived, stored in a separate httpOnly cookie) to get new access tokens without asking for credentials again.

app.post('/refresh', (req, res) => {
  const refreshToken = req.cookies.refreshToken;
  if (!refreshToken) return res.status(401).send('No refresh token');

  try {
    const decoded = jwt.verify(refreshToken, process.env.REFRESH_SECRET);
    const newAccessToken = jwt.sign(
      { sub: decoded.sub },
      process.env.JWT_SECRET,
      { expiresIn: '15m' }
    );
    res.cookie('token', newAccessToken, { httpOnly: true, secure: true, sameSite: 'strict' });
    res.json({ message: 'Token refreshed' });
  } catch (err) {
    return res.status(403).send('Invalid refresh token');
  }
});

What JWT Does NOT Solve

CSRF: If you use cookies, you need CSRF protection. Use SameSite=Strict or CSRF tokens.
Token revocation: JWT is stateless. You can't revoke a single token unless you maintain a blacklist (which defeats statelessness). For logout, clear the cookie on the server side or use short expiry.
Payload tampering: The signature ensures integrity. Never trust the payload without verifying the signature.

Common Pitfalls

Storing secrets in code: Use environment variables.
Using weak secrets: Use a long, random string (e.g., openssl rand -hex 64).
Not validating algorithms: If your server accepts 'none' algorithm, attackers can forge tokens. Always specify allowed algorithms.

// Explicitly set algorithms
jwt.verify(token, secret, { algorithms: ['HS256'] });

Summary

JWT is a tool, not a silver bullet. Use httpOnly cookies, short-lived tokens, refresh tokens, and proper CSRF protection. Understand the tradeoffs: statelessness vs. revocation. Keep it simple.

API Pagination Patterns: Offset vs Cursor vs Keyset

Stack Horizon — Wed, 29 Jul 2026 08:00:19 +0000

Why Pagination Matters

If you've ever built an API endpoint that returns a list, you've probably faced the question: what happens when the list has 10,000 items? Returning them all at once is a recipe for slow responses, memory exhaustion, and angry mobile users. Pagination is the answer, but not all pagination is created equal. Let's look at the three most common patterns: offset, cursor, and keyset pagination.

Offset Pagination (The Classic)

This is the simplest approach. The client sends page and per_page (or limit and offset), and the server skips that many rows.

# Flask example
@app.route('/items')
def get_items():
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 20, type=int)
    offset = (page - 1) * per_page
    items = db.execute('SELECT * FROM items ORDER BY id LIMIT ? OFFSET ?', (per_page, offset))
    return jsonify(items)

Pros:

Easy to implement and understand.
Works with any database, even in-memory lists.
Allows jumping to any page directly.

Cons:

Performance degrades with large offsets. The database still scans all skipped rows. On a table with 1 million rows, OFFSET 999980 is painfully slow.
Inconsistent results if rows are inserted/deleted. If a new row is added between requests, the same page might show different items.

Cursor Pagination (The Reliable One)

Instead of page numbers, the client passes a cursor (an opaque string) that points to the last item seen. The server returns items after that cursor.

@app.route('/items')
def get_items():
    cursor = request.args.get('cursor')
    per_page = request.args.get('per_page', 20, type=int)
    if cursor:
        # Decode cursor (e.g., base64 encoded ID)
        last_id = decode_cursor(cursor)
        items = db.execute('SELECT * FROM items WHERE id > ? ORDER BY id LIMIT ?', (last_id, per_page))
    else:
        items = db.execute('SELECT * FROM items ORDER BY id LIMIT ?', (per_page,))
    next_cursor = encode_cursor(items[-1]['id']) if len(items) == per_page else None
    return jsonify({'items': items, 'next_cursor': next_cursor})

Pros:

Fast and stable. Uses indexed columns (like id) to filter, so it scales to any offset.
Consistent. New rows don't shift pages because you always move forward from a specific point.
Real-time friendly. No duplicate or missed items when data changes.

Cons:

No random page access. You can't jump to page 5; you must traverse sequentially.
Cursor encoding adds complexity. You need to encode/decode the cursor (base64 is common).
Only works with sortable, unique fields. You need a column to order by (usually id or created_at).

Keyset Pagination (The SQL Optimized)

Similar to cursor, but uses the actual column values from the last row instead of an opaque token. Often used with composite keys.

@app.route('/items')
def get_items():
    last_id = request.args.get('last_id', type=int)
    last_created = request.args.get('last_created')
    per_page = request.args.get('per_page', 20, type=int)
    if last_id and last_created:
        items = db.execute('''
            SELECT * FROM items 
            WHERE (created_at, id) > (?, ?) 
            ORDER BY created_at, id 
            LIMIT ?
        ''', (last_created, last_id, per_page))
    else:
        items = db.execute('SELECT * FROM items ORDER BY created_at, id LIMIT ?', (per_page,))
    return jsonify({'items': items})

Pros:

Best performance. Uses database indexes efficiently, no OFFSET at all.
No cursor encoding needed. The client just passes raw column values.

Cons:

Tied to sort order. If you change the sort, the keyset changes.
Requires exposing column values. The client needs to know the last id or timestamp, which might be sensitive.
No random access. Like cursor pagination.

When to Use What

Offset pagination: Use for small datasets (under 10k rows) or when random page access is critical (e.g., admin panels).
Cursor pagination: Use for large, dynamic datasets where consistency matters (e.g., social feeds, activity logs).
Keyset pagination: Use when you need maximum performance and control over the sort order (e.g., real-time dashboards).

A Practical Compromise

Sometimes you can combine both: offer offset-based pagination for the first few pages (where performance is fine) and switch to cursor-based once the offset passes a threshold. But in most modern APIs, cursor pagination is the go-to choice. It's reliable, scalable, and the extra complexity is minimal.

Final Thought

Whichever pattern you choose, document it clearly. Your API consumers will thank you when they don't have to guess how to get the next page. And always test with large datasets to catch performance issues early.

Environment Config the Clean Way

Stack Horizon — Mon, 27 Jul 2026 16:02:50 +0000

The Problem with Environment Variables

We all know the drill. You clone a repo, create a .env file, and start coding. But soon the config grows messy. You have variables for dev, staging, production. Some are optional, some required. Your code is littered with os.getenv('SOME_VAR') and fallback logic. It's fragile and hard to maintain.

Let me show you a cleaner approach that I've used across several projects.

The Core Idea: A Config Object

Instead of scattering os.getenv calls everywhere, centralize all configuration into a single object. This object validates required variables, provides defaults, and gives you a single source of truth.

Here's a Python example using pydantic (but the concept applies to any language):

from pydantic import BaseSettings, Field

class Settings(BaseSettings):
    app_name: str = Field("MyApp", env="APP_NAME")
    debug: bool = Field(False, env="DEBUG")
    database_url: str = Field(..., env="DATABASE_URL")
    secret_key: str = Field(..., env="SECRET_KEY")
    port: int = Field(8000, env="PORT")

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

Now you access settings.database_url instead of os.getenv('DATABASE_URL'). Clean and type-safe.

Handling Multiple Environments

You can extend this pattern for different environments. Create a base config and inherit:

class BaseConfig(BaseSettings):
    database_url: str = Field(..., env="DATABASE_URL")
    secret_key: str = Field(..., env="SECRET_KEY")

class DevConfig(BaseConfig):
    debug: bool = True
    database_url: str = "sqlite:///dev.db"

class ProdConfig(BaseConfig):
    debug: bool = False
    database_url: str = Field(..., env="PROD_DATABASE_URL")

Then load the right one based on an environment variable:

import os

env = os.getenv("ENV", "dev")
if env == "prod":
    settings = ProdConfig()
else:
    settings = DevConfig()

Validation and Errors

One of the biggest wins is early validation. If DATABASE_URL is missing, your app fails immediately with a clear error message, not a cryptic database connection timeout later.

try:
    settings = Settings()
except Exception as e:
    print(f"Configuration error: {e}")
    sys.exit(1)

Keep Secrets Out of Code

Never hardcode secrets. Use .env files locally, and real secrets from your CI/CD pipeline or secret manager in production. The config object reads from environment variables, so you can inject them however you like.

What About Other Languages?

Node.js: Use env-var or convict for validation.
Go: Use envconfig or viper.
Rust: Use config crate with dotenv.

The pattern is the same: parse everything once, validate, and use a typed config object.

The Clean Way Checklist

Centralize all config in one module.
Validate required fields at startup.
Provide sensible defaults for non-critical vars.
Use typed fields to avoid stringly-typed code.
Never access os.getenv outside the config module.

Final Thoughts

This approach has saved me countless hours of debugging misconfigured environments. It's simple, testable, and scales from small scripts to large applications. Give it a try in your next project.

Happy coding!

REST vs GraphQL: A Practical Comparison

Stack Horizon — Thu, 23 Jul 2026 16:01:52 +0000

When to Use REST

REST has been the standard for API design for over a decade. It uses HTTP methods (GET, POST, PUT, DELETE) and resource-based URLs. REST is great when:

You have simple, CRUD-heavy operations
You want to leverage HTTP caching (e.g., GET requests can be cached)
Your API consumers are varied (web, mobile, third-party)
You need a straightforward, well-understood architecture

Example REST Endpoints

GET /api/users/123
GET /api/users/123/posts
POST /api/users
PUT /api/users/123
DELETE /api/users/123

REST works well for public APIs where you want to enforce a fixed schema. However, it suffers from over-fetching and under-fetching. For example, if a mobile client only needs a user's name and email, a REST endpoint that returns the full user object wastes bandwidth.

When to Use GraphQL

GraphQL, developed by Facebook, gives clients the power to ask for exactly what they need. It uses a single endpoint and a query language. GraphQL shines when:

You have complex, nested data relationships (e.g., user -> posts -> comments)
Your clients have varying data needs (mobile vs. desktop)
You want rapid iteration on the frontend without backend changes
You need to aggregate data from multiple sources

Example GraphQL Query

query {
  user(id: "123") {
    name
    email
    posts {
      title
      comments {
        text
      }
    }
  }
}

This query fetches only the requested fields, avoiding over-fetching. The response is predictable and matches the query structure.

Practical Trade-offs

Over-fetching and Under-fetching

REST often leads to over-fetching (getting too much data) or under-fetching (needing multiple requests). GraphQL solves this but introduces complexity: you need a resolver for every field, which can lead to N+1 queries if not optimized (use DataLoader).

Caching

REST benefits from HTTP caching (e.g., with ETags or Cache-Control). GraphQL typically uses a single POST endpoint, making caching harder. Solutions like persisted queries or CDN-level caching can help, but they add complexity.

Tooling and Ecosystem

REST has mature tooling (Swagger, Postman, etc.). GraphQL has excellent tools like Apollo Client, GraphiQL, and code generation. Both are well-supported, but GraphQL's tooling is more modern.

Learning Curve

REST is simpler to learn and debug. GraphQL requires understanding schemas, resolvers, and query optimization. For a small team or simple API, REST is often the better choice.

Code Example: Node.js Comparison

REST with Express

const express = require('express');
const app = express();

app.get('/api/users/:id', (req, res) => {
  const user = db.getUser(req.params.id);
  res.json(user);
});

app.listen(3000);

GraphQL with Apollo Server

const { ApolloServer, gql } = require('apollo-server');

const typeDefs = gql`
  type User {
    id: ID!
    name: String
    email: String
  }
  type Query {
    user(id: ID!): User
  }
`;

const resolvers = {
  Query: {
    user: (_, { id }) => db.getUser(id),
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
server.listen(4000);

GraphQL requires more boilerplate but gives flexibility.

My Recommendation

Start with REST if your API is simple or you need broad interoperability. Switch to GraphQL when you face over-fetching/under-fetching issues or when your frontend teams need more autonomy. Many projects use both: REST for public endpoints and GraphQL for internal use.

Ultimately, choose based on your specific needs, not hype.

Debugging Node.js Like a Pro

Stack Horizon — Wed, 22 Jul 2026 00:01:10 +0000

Debugging Node.js Like a Pro

Debugging is an inevitable part of development. But with the right tools and techniques, you can turn it from a chore into a superpower. Here are my favorite ways to debug Node.js like a pro.

1. Use the Built-in Debugger

Node.js has a built-in debugger that you can start with the inspect flag:

node --inspect app.js

Then open chrome://inspect in Chrome. You'll see your app under "Remote Target". Click "inspect" to open DevTools. You get breakpoints, step-through, console, and even memory profiling.

For a simpler CLI experience, use node inspect:

node inspect app.js

This gives you a debug> prompt where you can type commands like cont, next, step, and watch('variable').

2. Leverage the Async Debugging

Node.js 8+ added async hooks to the debugger. When you set a breakpoint inside an async function, the debugger pauses at the correct location, even if the call stack is complex. No more lost async chains!

3. Use `debug` Module for Logging

Instead of console.log everywhere, use the debug module:

npm install debug

const debug = require('debug')('app:server');
debug('Server started on port %d', port);

Run with:

DEBUG=app:* node app.js

You get color-coded, namespaced logs that you can turn on/off per module. No more messy console.log cleanup.

4. Master the Error Stack Trace

Always create meaningful error messages. Use Error.captureStackTrace to customize stack traces:

class MyError extends Error {
  constructor(message) {
    super(message);
    Error.captureStackTrace(this, this.constructor);
  }
}

And when logging errors, log the whole object, not just error.message:

console.error(error); // Good
console.error(error.stack); // Even better

5. Use `--trace-warnings` and `--trace-deprecation`

These flags show you where deprecations and warnings originate:

node --trace-warnings app.js
node --trace-deprecation app.js

They print the full stack trace for each warning, so you can fix the root cause immediately.

6. Profile Memory and CPU

The Chrome DevTools profiler is your friend. Use the --inspect flag and go to the "Memory" and "Performance" tabs. Take heap snapshots, record allocation timelines, and find memory leaks.

For CPU profiling, you can also use the built-in --prof flag:

node --prof app.js

This generates an isolate-*.log file. Process it with:

node --prof-process isolate-*.log > profile.txt

You'll get a breakdown of where Node.js spent its time.

7. Use `util.inspect` for Deep Objects

When you need to log a complex object, console.log often truncates. Use util.inspect with options:

const util = require('util');
console.log(util.inspect(myObject, { showHidden: true, depth: null, colors: true }));

This shows everything, no hidden properties or nested objects cut off.

8. Set Breakpoints in Code

You can add debugger; statements directly in your code. When you run with --inspect, execution will pause there. It's great for conditional debugging:

if (user.role === 'admin') {
  debugger; // Only pause for admins
}

9. Use `node --check` for Syntax Errors

Before running, check for syntax errors:

node --check app.js

It parses the file without executing it. Saves time on trivial mistakes.

10. Automate with `nodemon` and `--inspect`

Combine nodemon with the debugger for auto-restart on changes:

nodemon --inspect app.js

Now you can edit and debug without restarting manually.

Final Thoughts

Debugging is a skill. The more tools you have, the faster you find bugs. Start with the built-in debugger, add debug for logging, and profile memory early. Your future self will thank you.

The Best Developers Don't Know Everything. They Know How to Learn.

Stack Horizon — Mon, 13 Jul 2026 14:47:05 +0000

Have you ever noticed how the best developers don't seem to know everything...

They just know how to figure things out.

At some point I stopped asking:

"Which framework should I learn next?"

And started asking:

"How does this actually work under the hood?"

That single mindset shift made learning every new framework much easier.

Frameworks change.
Patterns evolve.
Libraries get replaced.

But understanding APIs, databases, networking, architecture, and debugging keeps paying dividends year after year.

Curious developers almost always outperform developers who only chase the next trend.

What's one concept that completely changed the way you build software?

DEV Community: Stack Horizon

REST vs GraphQL in Practice

The Practical Differences

REST: Simple and Predictable

GraphQL: Flexible but Complex

Real-World Considerations

1. Team Experience

2. Client Needs

3. Performance

4. Tooling

A Hybrid Approach

My Take

Bottom Line

JWT Auth Without the Confusion

What JWT Actually Is

The Common Mistake: Storing JWT in localStorage

How to Implement JWT Auth (The Practical Way)

1. Login endpoint issues a JWT in a cookie

2. Middleware verifies the token on each request

3. Refresh tokens for longer sessions

What JWT Does NOT Solve

Common Pitfalls

Summary

API Pagination Patterns: Offset vs Cursor vs Keyset

Why Pagination Matters

Offset Pagination (The Classic)

Cursor Pagination (The Reliable One)

Keyset Pagination (The SQL Optimized)

When to Use What

A Practical Compromise

Final Thought

Environment Config the Clean Way

The Problem with Environment Variables

The Core Idea: A Config Object

Handling Multiple Environments

Validation and Errors

Keep Secrets Out of Code

What About Other Languages?

The Clean Way Checklist

Final Thoughts

REST vs GraphQL: A Practical Comparison

When to Use REST

Example REST Endpoints

When to Use GraphQL

Example GraphQL Query

Practical Trade-offs

Over-fetching and Under-fetching

Caching

Tooling and Ecosystem

Learning Curve

Code Example: Node.js Comparison

REST with Express

GraphQL with Apollo Server

My Recommendation

Debugging Node.js Like a Pro

Debugging Node.js Like a Pro

1. Use the Built-in Debugger

2. Leverage the Async Debugging

3. Use debug Module for Logging

4. Master the Error Stack Trace

5. Use --trace-warnings and --trace-deprecation

6. Profile Memory and CPU

7. Use util.inspect for Deep Objects

8. Set Breakpoints in Code

9. Use node --check for Syntax Errors

10. Automate with nodemon and --inspect

Final Thoughts

The Best Developers Don't Know Everything. They Know How to Learn.

3. Use `debug` Module for Logging

5. Use `--trace-warnings` and `--trace-deprecation`

7. Use `util.inspect` for Deep Objects

9. Use `node --check` for Syntax Errors

10. Automate with `nodemon` and `--inspect`