laravel-api-resources-and-pagination_skill

Overview

This skill teaches how to represent Eloquent models with Laravel API Resources while preserving pagination metadata and stable response shapes. It emphasizes keeping transport concerns out of models, using conditional fields, and designing cache-friendly JSON payloads. The goal is predictable APIs that clients and caches can rely on.

How this skill works

Wrap paginated queries with Resource::collection($query->paginate()) so Laravel returns items plus links and meta automatically. Use when(), mergeWhen(), and whenLoaded() inside resource classes to include fields only when appropriate, keeping the overall JSON structure consistent. Convert dates and nested resources explicitly to avoid leaking Eloquent objects and to produce cacheable primitives.

When to use it

• Returning lists of models with pagination and preserving links/meta for clients
• Exposing nested relationships only when they are loaded to avoid N+1 and payload bloat
• Conditionally including fields (e.g., private data, feature flags) without changing outer shape
• Preparing API responses that need to be cache-friendly and stable across versions
• Avoiding direct Eloquent serialization in controllers or background jobs

Best practices

• Always use Resource::collection($query->paginate()) instead of manual array building
• Prefer when()/mergeWhen()/whenLoaded() for conditional fields so keys remain stable
• Explicitly format dates (toAtomString or ISO 8601) and primitive values for caching
• Keep pagination links and meta intact — clients rely on them for navigation
• Version resources when changing contracts to prevent silent breaking changes

Example use cases

• An articles endpoint returning 20 posts per page with author nested only when loaded
• An admin list that includes sensitive fields via when() for authorized users
• A public feed where published_at is always ISO-formatted for client sorting and caching
• Switching to cursor pagination while preserving resource shapes and meta links
• Creating frontend-friendly JSON envelopes for Vue components consuming paginated data