API Design

API Design

API design patterns and conventions. Updated by the Reflect skill.

Last Updated

2025-01-28

RESTful Conventions

Endpoint Structure

Relationships

• Use nested paths for 1:1 relationships: /users/{id}/profile
• Use query params for 1:N relationships: /users/{id}/posts?limit=10
• Avoid nesting deeper than 2 levels

Response Format

Success Response

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Example"
  },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}

Error Response

{
  "success": false,
  "error": {
    "message": "User not found",
    "code": "USER_NOT_FOUND",
    "details": {
      "field": "user_id",
      "value": 999
    }
  }
}

HTTP Status Codes

Pagination

Query Parameters

GET /users?page=1&per_page=20&sort=created_at&order=desc

Response Structure

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "pages": 5
  },
  "links": {
    "first": "/users?page=1",
    "last": "/users?page=5",
    "prev": null,
    "next": "/users?page=2"
  }
}

Laravel Implementation

Controller Structure

class UserController extends Controller
{
    public function index(Request $request): JsonResponse
    {
        $page = $request->input('page', 1);
        $perPage = $request->input('per_page', 20);

        $users = User::paginate($perPage);

        return response()->json([
            'success' => true,
            'data' => $users->items(),
            'meta' => [
                'page' => $page,
                'per_page' => $perPage,
                'total' => $users->total(),
            ]
        ]);
    }
}

Next.js Implementation

API Route Structure

app/api/
├── users/
│   ├── route.ts          # GET /api/users, POST /api/users
│   └── [id]/
│       └── route.ts      # GET/PATCH/DELETE /api/users/[id]

Learned Patterns

This section grows as the Reflect skill learns from sessions

Session 2025-01-28

• Learned: Always include success boolean in responses for easy error checking
• Learned: Use ISO 8601 format for all timestamps
• Learned: Return 204 No Content for DELETE (not 200 with empty body)