API Response Consistency

Overview

API routes have inconsistent error response formats. Some return structured JSON with proper HTTP status codes, while others return plain text responses. This inconsistency makes client-side error handling more difficult.

Problem

JSON Response Format (Good)

Used in api/new/goal.ts and api/new/backlog.ts:

return new Response(JSON.stringify({ error: "Owner is required" }), {
  status: 400,
  headers: { "Content-Type": "application/json" },
});

Plain Text Response Format (Inconsistent)

Used in api/open/task.ts, api/close/task.ts, api/update/backlog.ts:

return new Response("Task is required", { status: 400 });

Affected Files

• src/pages/api/new/goal.ts - JSON format ✅
• src/pages/api/new/backlog.ts - JSON format ✅
• src/pages/api/open/task.ts - Plain text ❌
• src/pages/api/close/task.ts - Plain text ❌
• src/pages/api/open/goal.ts - Plain text ❌
• src/pages/api/close/goal.ts - Plain text ❌
• src/pages/api/open/idea.ts - Plain text ❌
• src/pages/api/close/idea.ts - Plain text ❌
• src/pages/api/update/backlog.ts - Plain text ❌

Solution

Create a unified response utility in src/lib/api-response.ts for consistent JSON responses across all API routes.

Proposed API

// Success responses
export function successResponse(data?: object, message?: string): Response

// Error responses
export function errorResponse(message: string, status: number): Response

// Common HTTP status code helpers
export function badRequest(message: string): Response
export function notFound(message: string): Response
export function serverError(message?: string): Response
export function unauthorized(message?: string): Response

Usage Example

// Before
return new Response("Task is required", { status: 400 });

// After
return badRequest("Task is required");

// Before
return new Response(JSON.stringify({ error: "Owner is required" }), {
  status: 400,
  headers: { "Content-Type": "application/json" },
});

// After
return badRequest("Owner is required");

Benefits

• ✅ Consistency: All API routes return JSON with same structure
• ✅ Client-Friendly: Front-end can handle errors predictably
• ✅ Less Boilerplate: Reduced repetition in API route files
• ✅ Standards Compliant: Proper Content-Type headers on all responses

Implementation Notes

• Standard response structure: { success: boolean, data?: any, error?: string, message?: string }
• Ensure proper Content-Type: application/json headers
• Consider adding request ID for debugging

Related Files

• src/pages/api/new/goal.ts
• src/pages/api/new/backlog.ts
• src/pages/api/open/*.ts
• src/pages/api/close/*.ts
• src/pages/api/update/*.ts