Review API

API Design Review

Evaluate API design for correctness, consistency, usability, and security.

Cross-reference: api/knowledge-rest-principles for REST constraints and resource modeling.

When to Use

• Before merging new or modified API endpoints
• When reviewing OpenAPI/Swagger specs or GraphQL schemas
• When evaluating API backward compatibility
• During API design reviews before implementation

Severity Levels

Review Checklist

1. Resource Design

2. HTTP Semantics

Status code quick reference:

3. Error Handling

Standard error format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ]
  }
}

4. Pagination, Filtering, and Sorting

5. Versioning

6. Security

7. Backward Compatibility

8. Documentation

Output Format

## API Review: [API/Endpoint Name]

**Scope**: [Endpoints reviewed]
**Overall**: [PASS | PASS WITH WARNINGS | FAIL]

### Findings

#### Design
##### [WARNING] Verb in resource name
**Location**: `POST /api/createUser`
**Issue**: Resource uses verb instead of noun
**Fix**: `POST /api/users` — the HTTP method implies creation

#### Security
##### [CRITICAL] Missing auth on admin endpoint
**Location**: `GET /api/admin/users`
**Issue**: No authentication middleware
**Fix**: Add auth middleware and admin role check

...

### Summary
| Category | Critical | Warning | Suggestion |
|----------|----------|---------|------------|
| Design | 0 | 2 | 1 |
| HTTP Semantics | 0 | 1 | 0 |
| Error Handling | 0 | 1 | 0 |
| Pagination | 1 | 0 | 1 |
| Security | 1 | 1 | 0 |
| Compatibility | 0 | 0 | 0 |
| Documentation | 0 | 2 | 0 |
| **Total** | **2** | **7** | **2** |

### Recommendations
1. <Prioritized by impact>
2. ...