Modern REST API Design: Standards, Security, and Error Handling Best Practices

The Anatomy of an Enterprise-Grade REST API

APIs are the digital glue connecting mobile applications, frontend web clients, and third-party partner integrations. A poorly designed API creates technical debt, security vulnerabilities, and developer frustration. Follow these proven principles to build clean, intuitive APIs.

1. Resource-Centric URL Design

URLs should represent nouns and resources, never actions or verbs: - **Good**: `GET /api/v1/courses`, `POST /api/v1/courses`, `GET /api/v1/courses/:id/lessons` - **Bad**: `GET /api/v1/getAllCourses`, `POST /api/v1/createCourse`, `POST /api/v1/deleteCourse`

2. Precise Use of HTTP Methods

• **GET**: Retrieve representations of resources. Must be strictly read-only and idempotent.
• **POST**: Create a brand new resource or trigger an asynchronous processing job.
• **PUT**: Completely replace an existing resource with a new representation.
• **PATCH**: Partially modify specific fields of an existing resource.
• **DELETE**: Remove the specified resource. Must be idempotent.

3. Proper HTTP Status Codes

| Status Code | Meaning | When to Use | | :--- | :--- | :--- | | **200 OK** | Success | Successful GET, PUT, or PATCH. | | **201 Created** | Created | Successful POST resulting in a new resource. | | **204 No Content**| Success | Successful DELETE or operation with no response body. | | **400 Bad Request**| Client Error | Payload validation failed (e.g., invalid email format). | | **401 Unauthorized**| Auth Required | Missing or expired JWT bearer token. | | **403 Forbidden** | Access Denied | Authenticated user lacks RBAC permission. | | **404 Not Found** | Missing | Requested resource ID does not exist. | | **429 Too Many Requests** | Rate Limited | Client exceeded request quota within time window. | | **500 Internal Error**| Server Error | Unexpected unhandled exception logged on server. |

4. Standardized Problem Details (RFC 7807)

Instead of returning inconsistent error objects, adopt the RFC 7807 problem details specification:

```json { "type": "https://api.devvoltz.com/errors/validation-failed", "title": "Validation Failed", "status": 400, "detail": "The payload contains 2 invalid fields.", "instance": "/api/v1/bootcamp/registrations", "invalidParams": [ { "name": "phone", "reason": "Invalid international phone format" }, { "name": "email", "reason": "Email already registered" } ] } ```

5. API Security & Rate Limiting

• **JWT Authentication**: Issue short-lived Access Tokens (15 minutes) paired with rotating Refresh Tokens stored in `HttpOnly, Secure, SameSite=Strict` cookies.
• **Rate Limiting**: Protect endpoints against brute force and Denial of Service (DoS) attacks using Redis Token Bucket or Leaky Bucket algorithms (e.g., 60 requests/minute per IP).
• **CORS Configuration**: Restrict `Access-Control-Allow-Origin` strictly to your trusted client domains.