[W1.4] API Response Standardization

1. Front Matter

• Title: API Response Standardization

• Author: scorevi (Sean Patrick Caintic)

• Reviewers: itswyza (Yza Santiago)

• Created: January 2026

• Status: Approved

• References:

  • Issue: [W1.4] Quest W1.4 #113

  • Milestone: [W1] Backend Infrastructure

2. Introduction & Goals

• Problem Summary: Before W1.4, API routes returned inconsistent formats ({ success, data }, { data }, { message }). Error codes were ad-hoc or missing, making frontend parsing unreliable.

• Goals:

  • Unified response format: { success, data, error }

  • Standardized error codes (ApiErrorCode enum)

  • Helper class to enforce consistency

  • Auto-format Zod validation errors

• Non-Goals:

  • GraphQL support

  • Response compression

  • Response caching headers

• Glossary:

  • ApiResponseHelper: Utility class for building standardized responses

  • ApiErrorCode: Enum of standardized error codes

3. High-Level Architecture

• System Diagram:

• Technologies Used:

  • Next.js Route Handlers - API endpoints

  • Zod - Input validation

  • TypeScript - Type-safe responses

4. Detailed Design & Implementation

• Data Model / Schema:

  Success Response:

  Field	Type	Description
  success	true	Always true for success
  message	string?	Optional success message
  data	T	Response payload
  error	null	Always null on success

  Error Response:

  Field	Type	Description
  success	false	Always false on error
  message	string	Human-readable error
  data	null	Always null on error
  error.code	ApiErrorCode	Standardized error code
  error.message	string	Technical description
  error.details	unknown?	Optional context

• API Specification:

  Error Codes:

  • VALIDATION_ERROR (400) - Zod schema failed

  • BAD_REQUEST (400) - Malformed request

  • UNAUTHORIZED (401) - Not authenticated

  • FORBIDDEN (403) - Insufficient permissions

  • NOT_FOUND (404) - Resource not found

  • CONFLICT (409) - Duplicate/conflict

  • TOKEN_LIMIT_EXCEEDED (429) - Rate limit hit

  • INTERNAL_ERROR (500) - Server failure

• Logic & Workflows:

  Helper Methods:

  • success(data) - Standard success (200)

  • created(data) - Resource created (201)

  • badRequest(msg) - Invalid request (400)

  • unauthorized() - Not logged in (401)

  • forbidden() - No permission (403)

  • notFound() - Missing resource (404)

  • validationError(msg, details) - Schema fail (400)

  • internalError(msg) - Server error (500)

  • fromError(error) - Auto-parse exception (varies)

• Key Files:

  • lib/api/response.ts - ApiResponseHelper class

  • lib/api/validators.ts - Zod validation utilities

  • lib/api/verifyContentOwnership.ts - Access verification

5. Infrastructure & Operations

• Dependencies:

  • Next.js - Route handling

  • Zod - Validation

• Monitoring & Alerting: Standard error logging via console.error for 500 errors.

• Deployment Plan:

  1. Deploy helper class

  2. Migrate existing routes incrementally

  3. No breaking changes to frontend

6. Testing & Quality Assurance

• Test Strategy:

  • Unit: ApiResponseHelper methods

  • Integration: Route response formats

• Known Limitations:

  • No response caching

  • No pagination helpers (separate concern)

7. Maintenance & Support

• Troubleshooting:

  • Frontend not parsing errors → Verify error.code exists

  • Validation error details missing → Check error.details

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

Document Version

1.0 - Approved, Infrastructure deployed to production, 02/15/2026