20 API Design Best Practices Every Backend Engineer Should Know

Good API design is about creating APIs that are easy to understand, consistent, secure, scalable, and maintainable. Here are the most important best practices used in modern REST APIs.

20 API Design Best Practices

1. Use Resource-Oriented URLs

Use nouns, not verbs.

✅ Good

GET    /users
GET    /users/123
POST   /users
PUT    /users/123
DELETE /users/123

❌ Avoid

GET /getUsers
POST /createUser
DELETE /deleteUser/123

2. Use HTTP Methods Correctly

Use HTTP Methods Correctly

Example:

PATCH /users/123

{
  "firstName": "John"
}

3. Use Consistent Naming

Choose one convention and stick to it.

Common practice:

/users
/user-roles
/course-enrollments

Avoid mixing:

/userRoles
/user_roles
/UserRoles

4. Version Your APIs

Never break existing clients.

/api/v1/users
/api/v2/users

or

Accept: application/vnd.company.v2+json

URL versioning is usually simpler.

5. Return Proper HTTP Status Codes

Success

200 OK
201 Created
204 No Content

Client Errors

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Unprocessable Entity

Server Errors

500 Internal Server Error
503 Service Unavailable

Example:

POST /users

201 Created
Location: /users/123

6. Design Meaningful Response Bodies

Response:

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

Avoid:

{
  "status": 1
}

Clients shouldn’t need to guess.

7. Standardize Error Responses

A consistent error format saves developers hours.

{
  "code": "USER_NOT_FOUND",
  "message": "User does not exist",
  "details": {
    "userId": 123
  }
}

For validation:

{
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email address"
    }
  ]
}

8. Support Filtering, Sorting, and Pagination

Filtering

GET /users?status=active

Sorting

GET /users?sort=name
GET /users?sort=-createdAt

Pagination

GET /users?page=1&pageSize=20

Response:

{
  "items": [...],
  "page": 1,
  "pageSize": 20,
  "totalItems": 542,
  "totalPages": 28
}

9. Avoid Deeply Nested URLs

✅ Good

/users/123/orders

❌ Too deep

/companies/1/departments/2/teams/3/users/123/orders

Use query parameters when relationships become complex.

10. Make APIs Idempotent When Appropriate

Calling the same request multiple times should not produce unexpected results.

PUT /users/123

should always leave the resource in the same state.

This becomes critical when handling retries.

11. Use Request Validation

Validate:

• Required fields
• Data types
• String lengths
• Business rules

Example:

{
  "email": "invalid-email"
}

Return:

422 Unprocessable Entity

with detailed validation errors.

12. Secure Everything

Authentication

• OAuth2
• JWT
• API Keys

Authorization

Don’t only authenticate. Check permissions:

Can user edit this course?
Can user view this school?

Additional Security

• Rate limiting
• Input sanitization
• HTTPS only
• Audit logging

13. Use OpenAPI (Swagger)

Document APIs in a machine-readable format.

Benefits:

• Interactive testing
• SDK generation
• Better collaboration
• Easier onboarding

Popular tools:

• Swagger
• Redocly

14. Make Responses Backward Compatible

Avoid removing fields.

Bad:

{
  "fullName": "John Doe"
}

Later changing to:

{
  "name": "John Doe"
}

This breaks clients.

Prefer adding new fields and deprecating old ones gradually.

15. Support Correlation IDs

Support Correlation IDs means adding a unique identifier to every API request so it can be traced across all services in a system.

This ID is passed from the client through all backend services and included in logs, making it much easier to debug issues, track request flow, and diagnose failures in distributed systems or microservices.

Request:

X-Correlation-ID: abc123

Response:

X-Correlation-ID: abc123

Logs:

[abc123] User created successfully

16. Be Careful With Bulk Operations

Instead of:

POST /users

1000 times

Provide:

POST /users/bulk

Response:

{
  "successful": 980,
  "failed": 20
}

Useful for integrations and imports.

17. Keep Business Logic Out of Controllers

A common architecture:

Controller
    ↓
Application Service
    ↓
Domain
    ↓
Repository

For example, in NestJS/Clean Architecture:

Presentation Layer
    ↓
Application Layer
    ↓
Domain Layer
    ↓
Infrastructure Layer

Controllers should orchestrate requests, not contain business rules.

18. Design for Observability

Log:

• Request ID
• User ID
• Execution time
• Errors

Expose metrics:

• Request count
• Error rate
• Latency
• Throughput

This becomes essential as systems scale.

19. Prefer Consistency Over Cleverness

If one endpoint returns:

{
  "items": []
}

all collection endpoints should do the same.

Don’t mix:

{
  "users": []
}

and

{
  "items": []
}

Consistency is one of the biggest factors in API usability.

20. Think About Future Evolution

Before creating an endpoint ask:

• Can this scale to millions of requests?
• Can it support new fields?
• Can clients retry safely?
• Can it work in microservices?
• Will it be easy to document?

Good API design is less about today’s requirements and more about avoiding tomorrow’s problems.

A Production-Grade Example

GET /api/v1/users?page=1&pageSize=20&status=active&sort=-createdAt

Response:

{
  "items": [
    {
      "id": "123",
      "name": "John Doe",
      "email": "john@example.com"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalItems": 1250,
  "totalPages": 63
}

Headers:

200 OK
X-Correlation-ID: abc123

This style is commonly used by large-scale APIs from companies like Stripe and GitHub, because it remains maintainable as systems grow.

Thanks for reading…… If you enjoyed this article, consider following for more content on backend development, API design, and system architecture.

Feel free to share your thoughts or experiences in the comments — your feedback helps improve future articles.❤️