DEV Community

Cover image for 10 REST API MISTAKES TO AVOID
Abiodun Paul Ogunnaike
Abiodun Paul Ogunnaike

Posted on

10 REST API MISTAKES TO AVOID

#restapi #webdev #data #php

If you're building APIs with Wordpress, Laravel or Node.js, this might hit a bit close to home

A lot of developers aren’t really designing APIs
they’re just returning JSON and calling it a day.

And that’s where things start to fall apart.

Because a solid API isn’t just something that “works.”
It should be consistent, scalable, predictable, and easy for other developers to use.

Let’s break down some of the most common mistakes and how to fix them 👇

❌ 1. Using Verbs in URLs

Wrong

GET /getBooks  
POST /createBook 
DELETE /deleteBook/1
Enter fullscreen mode Exit fullscreen mode

Right

GET /books  
POST /books 
DELETE /books/1
Enter fullscreen mode Exit fullscreen mode

👉 URLs should represent resources (nouns) — not actions.
HTTP methods already define the action.

❌ 2. Ignoring HTTP Status Codes

Wrong

200 OK
{ "status": "error", "message": "User not found" }
Enter fullscreen mode Exit fullscreen mode

Right

  • 200 → Success
  • 201 → Created
  • 400 → Bad Request
  • 401 → Unauthorized
  • 403 → Forbidden
  • 404 → Not Found
  • 422 → Validation Error
  • 500 → Server Error

👉 Status codes are part of your API contract.

❌ 3. Inconsistent JSON Structure

Wrong

{ "userName": "Paul" }
{ "username": "Paul" }
Enter fullscreen mode Exit fullscreen mode

Right

  • Pick one style: snake_case OR camelCase
  • Use it everywhere

👉 Consistency builds trust.

❌ 4. No API Versioning

Wrong

/books
Enter fullscreen mode Exit fullscreen mode

Right

/api/v1/books
/api/v2/books
Enter fullscreen mode Exit fullscreen mode

👉 Versioning prevents breaking existing clients.

❌ 5. No Pagination

Wrong

GET /books → returns 10,000 records
Enter fullscreen mode Exit fullscreen mode

Right

GET /books?page=1&limit=10
{
  "data": [],
  "meta": {
    "current_page": 1,
    "total": 1000
  }
}
Enter fullscreen mode Exit fullscreen mode

👉 Pagination improves performance, scalability, and UX.

❌ 6. Mixing Authentication & Authorization

  • Authentication = Who are you?
  • Authorization = What can you do?

👉 Use proper tools:

  • JWT / OAuth
  • Laravel Sanctum / Passport
  • Never trust frontend validation alone.

❌ 7. Poor Error Handling

Bad

"Something went wrong"
Enter fullscreen mode Exit fullscreen mode

Good

{
  "error": {
    "code": 404,
    "message": "Book not found"
  }
}
Enter fullscreen mode Exit fullscreen mode

👉 Errors should be predictable and structured.

❌ 8. Bad Filtering & Sorting

Wrong

GET /getActiveEventsSortedByName
Enter fullscreen mode Exit fullscreen mode

Right

GET /events?status=active&sort=name
Enter fullscreen mode Exit fullscreen mode

👉 Keep it clean, flexible, and scalable.

❌ 9. Ignoring Security

Common mistakes:

  • No rate limiting
  • No validation
  • No HTTPS
  • Exposing sensitive data

👉 Best practices:

  • Always use HTTPS
  • Validate all inputs
  • Add rate limiting
  • Hide sensitive/internal fields

❌ 10. Designing APIs Around Your Database

Bad mindset

“This is my table structure”

Good mindset

“This is what the client needs”

👉 Your API is a contract, not a database mirror.

What Good APIs Look Like

  • Versioned endpoints
  • Consistent naming
  • Proper status codes
  • Pagination
  • Filtering & sorting
  • Secure authentication
  • Structured errors
  • Resource-based URLs

REST API design isn’t about returning JSON.

It’s about:

  • Consistency
  • Scalability
  • Predictability
  • Security
  • Developer Experience

When your API is clean and predictable…
developers love working with it.

Top comments (0)