API Security and Best Practices

In the previous posts, I covered what REST is and how resources and methods work. Now let's look at what makes an API robust: status codes that communicate clearly, security that protects your data, and design patterns that keep things maintainable. These are the things I wish I'd understood better when I started building APIs.

Status Codes

HTTP status codes tell the client what happened. Using them correctly makes APIs predictable and easier to debug.

2xx codes mean success. 200 OK for successful GET, PUT, or PATCH. 201 Created when POST creates a new resource. 204 No Content for successful DELETE (the response body is empty).

4xx codes mean the client made a mistake. 400 Bad Request for malformed input. 401 Unauthorized when authentication is missing or invalid. 403 Forbidden when authenticated but lacking permission. 404 Not Found when the resource doesn't exist. 409 Conflict for validation errors like duplicate emails.

5xx codes mean the server failed. 500 Internal Server Error for unexpected crashes. 503 Service Unavailable during maintenance or overload.

Using standard codes matters because clients can handle errors consistently across different APIs. A 401 always means "authenticate first," regardless of whose API you're calling.

Security

APIs need protection. I've learned these essentials the hard way:

Authentication verifies who's calling. API keys are simple but easy to leak. Token-based authentication (like JWT) is more secure: after logging in, the client gets a token that expires and can encode permissions. OAuth handles delegated access, like when an app needs to access your Google data.

Authorization controls what authenticated users can do. A regular user might read data but not delete it. An admin has broader access. The API should check permissions on every request.

HTTPS encrypts data in transit. Never run an API over plain HTTP. Man-in-the-middle attacks can intercept credentials and data.

Rate limiting prevents abuse. Limit requests per client per time period. This protects against denial-of-service attacks and ensures fair usage. Return 429 Too Many Requests when limits are exceeded.

Input validation blocks injection attacks. Validate and sanitize all input. Use parameterized queries for database access. Never trust data from clients.

Design Patterns

A few conventions that I've found make APIs easier to use and maintain:

Use nouns for resources. URLs should identify things, not actions. GET /orders/456 is good. GET /getOrder/456 is not. The HTTP method already expresses the action.

Use plural nouns. /users/123 represents one user from the users collection. Consistency matters more than grammar debates.

Nest related resources. To get orders for a user: GET /users/123/orders. The URL structure reflects the relationship.

Version your API. APIs evolve, and changes can break clients. Versioning gives clients time to migrate. /v1/users and /v2/users can coexist. Some prefer header versioning, but URL versioning is simpler and more visible.

Support pagination. Large collections need limits. GET /products?page=2&limit=20 returns a manageable chunk. Include metadata about total count and available pages.

Return meaningful errors. When something goes wrong, explain what. A JSON body with error code and message helps developers debug:

{
  "status": 404,
  "error": "User not found"
}

Challenges

REST isn't perfect. Some operations don't fit CRUD cleanly. How do you model "approve membership" or "transfer funds"? These actions sit awkwardly in a resource-oriented world.

Fetching related data can be inefficient. Getting a user and their orders might require multiple requests. GraphQL emerged partly to address this, letting clients request exactly the data they need in one call.

Statelessness, while beneficial for scaling, means authentication tokens travel with every request. Session-based approaches are simpler for some use cases.

These tradeoffs are real, but REST remains the default for good reasons. It's simple, widely understood, and works well for most applications. The constraints promote consistency and interoperability.

For most APIs, REST is still the right starting point.