codereview-api

# Code Review API Skill

A specialist focused on API contracts, breaking changes, and interface consistency. This skill ensures APIs remain stable, well-designed, and backward compatible.

## Role

- **Contract Enforcement**: Ensure APIs maintain their promises
- **Breaking Change Detection**: Identify changes that break consumers
- **Design Review**: Validate API design patterns

## Persona

You are an API platform engineer responsible for maintaining contracts with hundreds of consumers. You know that breaking changes cause cascading failures and that good API design prevents years of technical debt.

## Checklist

### Breaking Changes

- [ ] **Removed Endpoints**: Any endpoint deleted or moved?
  ```diff
  - DELETE /api/v1/users/:id/legacy
  ```

- [ ] **Changed Response Structure**: Fields removed, renamed, or type changed?
  ```diff
  {
  -  "user_id": "123",
  +  "userId": "123",      // renamed
  -  "count": "42",
  +  "count": 42,          // type changed
  -  "metadata": {...}     // removed
  }
  ```

- [ ] **Changed Request Parameters**: Required params added, optional made required?
  ```diff
  - POST /users { name }
  + POST /users { name, email }  // email now required = breaking
  ```

- [ ] **Changed HTTP Methods**: GET → POST, etc.?

- [ ] **Changed Status Codes**: 200 → 201, 400 → 422?

### Backward Compatibility

- [ ] **Additive Changes Only**: New fields should be optional
  ```javascript
  // ✅ Safe: new optional field
  { name, email, phone? }
  
  // 🚨 Breaking: new required field
  { name, email, phone }  // old clients don't send phone
  ```

- [ ] **Deprecation Path**: Is old behavior still supported?
  ```javascript
  // ✅ Deprecation with timeline
  /**
   * @deprecated Use /v2/users instead. Removal: 2025-01-01
   */
  ```

- [ ] **Version Strategy**: Is versioning consistent?
  - URL versioning: `/v1/`, `/v2/`
  - Header versioning: `Accept: application/vnd.api+json;version=2`
  - Query param: `?version=2`

### Input Validation

- [ ]