LUC #83: 8 Common Mistakes to Avoid in API Design

Plus, how does SSH actually work, concurrency is NOT parallelism, and the most popular deployment strategies explained

This week’s issue brings you:

READ TIME: 5 MINUTES

Thanks to our partners who keep this newsletter free to the reader.

POST/CON 25: Build Smarter APIs for an AI-Driven World

Join 2,000+ engineers at POST/CON 25, June 3 & 4 in LA, for deep dives on building scalable APIs, automating with Flows, and deploying AI-native systems. 30+ sessions, hands-on workshops, and zero fluff. Learn from Postman engineers and peers solving real-world problems.

8 Common Mistakes to Avoid in API Design

Clean, reliable APIs are a hallmark of strong engineering teams.

They don't happen by accident — they happen by design.

Let's walk through 8 critical mistakes to watch for when crafting APIs that stand the test of time.

1) Not Validating User Inputs

Input validation is your API’s first line of defense.

Accepting unvalidated data leaves you vulnerable to injection attacks, corrupted databases, and confusing downstream errors. Always validate inputs on the server side; not just for type and format, but also for business logic. Assume nothing about client behavior.

Tip: Use schema validation libraries or frameworks to enforce strict rules at your API boundaries.

2) Weak Security

Security can't be an afterthought. Common oversights include exposing sensitive data, improperly handling authentication tokens, or missing encryption on data in transit. A single weak endpoint can compromise your entire system.

Tip: Apply principles like least privilege, secure authentication (OAuth 2.0, OpenID Connect), encrypted communication (TLS), and regular security audits across your API surface.

3) Overcomplicating the API

A powerful API isn’t necessarily a complex one.

When you overload endpoints with too many responsibilities, mix resources and actions, or create deeply nested payloads, you make your API harder to learn, harder to use, and harder to maintain.

Tip: Stick to clear, predictable patterns. One resource → one endpoint. One action → one HTTP method.

4) Lack of Clear Documentation

The best API in the world won't gain adoption without great docs.

Unclear documentation forces developers to guess how your API works — leading to mistakes, frustration, and support tickets.

Tip: Invest in easy-to-navigate documentation, examples, and usage guides. Tools like Swagger/OpenAPI and Postman can help you automatically generate high-quality docs from your API definitions.

5) Poor Error Handling

Errors are inevitable — unclear errors are unforgivable.

Vague 500 errors, inconsistent error formats, and missing error codes make debugging a nightmare for users.

Tip: Standardize your error responses. Include meaningful HTTP status codes, error messages, and even error IDs that developers can reference for troubleshooting.

6) Not Rate Limiting

Without rate limiting, a single client can unintentionally (or maliciously) overwhelm your API and bring your system down. This isn’t just a problem for high-traffic APIs — any public-facing service needs basic protections against spikes.

Tip: Implement sensible rate limits (eg; 1,000 requests/minute per API key) and return clear error messages (HTTP 429) when limits are exceeded.

7) Not Implementing Versioning

APIs evolve, but your users shouldn’t suffer every time you make a change. Without versioning, even minor updates can break client applications that depend on your previous behavior.

Tip: Plan for API versioning from day one. Common strategies include path versioning (/v1/users) or header-based versioning (Accept: application/vnd.company.v1+json).

8) Ignoring Performance Optimization

An API might work fine at low scale, but poor performance can quietly become a huge bottleneck as adoption grows. Inefficient queries, redundant data transfers, and lack of caching can grind systems to a halt.

Tip: Monitor and optimize your most critical endpoints. Techniques like pagination, compression, selective fields (fields=id,name), and caching (ETags, HTTP caching) make a big difference.

Final Thoughts

Your API is a product — even if it’s "internal." Treat it like one.

Clear contracts, secure practices, thoughtful UX, and strong documentation aren’t just "nice to have"; they determine whether developers love integrating with your systems or dread it.

Every decision you make at the design stage pays compounding dividends later. Start strong, and you’ll save yourself (and your users) a lot of pain.

How Does SSH Actually Work? (Recap)

SSH (Secure Shell) establishes a secure connection to remote machines by performing a key exchange, verifying the server's identity, setting up encrypted communication, and authenticating the client — ensuring confidentiality, integrity, and authentication before allowing secure interaction.

At a high level, the connection process includes:

1) Key Exchange: Client and server establish a shared secret for encryption.

2) Server Verification: Client checks the server’s identity to prevent MITM attacks.

3) Encryption Setup: A symmetric session key secures all communication.

4) Client Authentication: Client proves its identity using public key cryptography.

Concurrency is NOT Parallelism (Recap)

As Rob Pike (one of the creators of Golang) succinctly put it: “Concurrency is about dealing with lots of things at once. Parallelism is about doing lots of things at once."

Concurrency — Manages several tasks on a single processor, creating an illusion of simultaneous execution by switching between tasks. This optimizes processor time, especially when tasks wait for others to complete.

Parallelism — Performs multiple tasks simultaneously by efficiently utilizing multiple processors or cores in a computing system.

Blue/green deployment: Uses two environments to ensure zero downtime; one hosts the live version while the other tests new updates. This setup allows for an easy rollback if needed.

Canary deployment: Rolls out changes to a small subset of users first, enabling performance monitoring and gathering feedback. If successful, the update can be gradually extended to more users.

Rolling deployment: Updates the software in phases, ensuring most of the system remains operational. It’s ideal for systems that require continuous operation.

Feature toggles: Acts like switches for new features. They allow teams to deploy features quietly, turning them on for specific users when it makes sense.

A/B testing: Tests different feature versions with various user groups to identify the most effective one. Useful for validating user preference and effectiveness based on concrete data.

That wraps up this week’s issue of Level Up Coding’s newsletter!

Join us again next week, where we’ll explore and visually distil more important engineering concepts.