Logo
Matt's posts
Back to all posts
·2 min read

Building Better APIs: Lessons from a Decade of REST

apiarchitecturebackend

After building and maintaining APIs for over a decade, I've seen patterns come and go. Some stood the test of time; others were just noise. Here's what I've learned.

Start with the Consumer

The best APIs are designed from the outside in. Before writing any code, sketch out how a client would actually use your API. What calls do they need to make? What data do they need back?

// Bad: exposing your internal model
GET /api/v1/user_account_records?include_deleted=false&active_status=1

// Good: consumer-focused
GET /api/users/active

This seems obvious, but it's remarkable how often we let database schemas leak into API designs.

Versioning: Keep It Simple

I've seen teams agonize over versioning strategies. URL versioning, header versioning, content negotiation—each has trade-offs. Here's the secret: it doesn't matter that much.

Pick URL versioning (/api/v1/) and move on. It's visible, cacheable, and everyone understands it. The time you save not debating this can go toward actually building features.

Error Responses That Help

Your errors should tell developers exactly what went wrong and how to fix it:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "email",
        "issue": "Must be a valid email address",
        "received": "not-an-email"
      }
    ],
    "documentation": "https://api.example.com/docs/errors#validation"
  }
}

Compare this to {"error": "Bad Request"}. Which would you rather debug at 2am?

Rate Limiting from Day One

Don't wait until you have a scaling problem. Implement rate limiting early:

  1. It forces you to think about resource costs
  2. It protects you from accidental abuse
  3. It's much harder to add later without breaking clients

Return proper 429 responses with Retry-After headers. Your future self will thank you.

The Pragmatic Path

The best API isn't the most theoretically pure—it's the one that developers actually enjoy using. Optimize for clarity, consistency, and helpful error messages. Everything else is secondary.

Read more posts