api-design

name	API Design
description	API design patterns and REST conventions. Use for any API work - endpoint design, response formats, error handling, pagination, status codes. Contains learned preferences for Laravel and Next.js API patterns.

API Design

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

Last Updated

2025-01-28

RESTful Conventions

Endpoint Structure

Pattern	Example	Description
GET /resources	GET /users	List all resources
GET /resources/{id}	GET /users/123	Get single resource
POST /resources	POST /users	Create new resource
PUT /resources/{id}	PUT /users/123	Replace resource
PATCH /resources/{id}	PATCH /users/123	Partial update
DELETE /resources/{id}	DELETE /users/123	Delete resource

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

Code	Usage	Example
200	Success (GET, PATCH)	User retrieved successfully
201	Created (POST)	User created successfully
204	No Content (DELETE)	User deleted successfully
400	Bad Request	Validation failed
401	Unauthorized	Not logged in
403	Forbidden	Logged in, no permission
404	Not Found	Resource doesn't exist
422	Unprocessable Entity	Validation error
500	Server Error	Something went wrong

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)