playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / api

api skill

/skills/laravel/api

This skill helps you implement Laravel API best practices with resource formatting, versioned routes, and token-based authentication for secure, scalable

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill api

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.3 KB
---
name: Laravel API
description: REST and JSON API standards for modern Laravel backends.
metadata:
  labels: [laravel, api, rest, json, sanctum]
  triggers:
    files: ['routes/api.php', 'app/Http/Resources/**/*.php']
    keywords: [resource, collection, sanctum, passport, cors]
---

# Laravel API

## **Priority: P1 (HIGH)**

## Structure

```text
app/
└── Http/
    ├── Resources/      # Data transformation
    └── Controllers/
        └── Api/        # API specific logic
```

## Implementation Guidelines

- **API Resources**: Always use Resources/Collections for JSON formatting.
- **RESTful Actions**: Follow standard naming (`index`, `store`, `update`).
- **Auth**: Use **Sanctum** for SPAs/Mobile or **Passport** for OAuth2.
- **Status Codes**: Return appropriate HTTP codes (201 Created, 422 Unprocessable).
- **Versioning**: Prefix routes with version tags (e.g., `api/v1/...`).
- **Rate Limiting**: Configure `RateLimiter` to protect public endpoints.

## Anti-Patterns

- **Raw Models**: **No raw model returns**: Information leakage risk.
- **Manual JSON**: **No response()->create()**: Use API Resources.
- **Session Auth**: **No sessions for APIs**: Use Tokens (Sanctum).
- **Hardcoded URLs**: **No static links in JSON**: Use HATEOAS or route names.

## References

- [API Resource Patterns](references/implementation.md)

Overview

This skill captures REST and JSON API standards for modern Laravel backends, focusing on secure, consistent, and maintainable API design. It summarizes structure, conventions, and high-priority rules to help agents generate and review Laravel APIs that follow best practices. The guidance targets controllers, resources, authentication, versioning, and rate limiting.

How this skill works

The skill inspects controller layout and resource usage, ensuring API-specific controllers live under a dedicated namespace and JSON formatting is done via API Resources/Collections. It validates use of token-based auth (Sanctum or Passport), proper HTTP status codes, route versioning, and configured rate limiting while flagging anti-patterns like raw model returns or manual JSON building.

When to use it

  • Scaffolding or reviewing Laravel API endpoints for consistency and security
  • Converting legacy session-based endpoints to token-based APIs
  • Enforcing consistent JSON output and HTTP status codes across teams
  • Designing public APIs that require versioning and rate limiting
  • Auditing responses to prevent information leakage from raw models

Best practices

  • Keep API controllers in a dedicated API namespace and use Resources/Collections for all JSON formatting
  • Follow RESTful action names (index, show, store, update, destroy) and return appropriate HTTP status codes
  • Use Sanctum for SPA/mobile token auth or Passport for OAuth2 flows; avoid session auth for APIs
  • Prefix routes with a version tag (e.g., api/v1) and design version-compatible changes
  • Configure RateLimiter for public endpoints to protect against abuse
  • Avoid returning Eloquent models directly or building JSON manually; use resources and HATEOAS or route helpers for links

Example use cases

  • Generate a new API controller scaffold that follows api/v1 routing and uses a Resource for responses
  • Review an existing endpoint to replace raw model returns with a Resource collection and correct status codes
  • Migrate session-authenticated endpoints to Sanctum token authentication for a mobile client
  • Add rate limiting to a public search endpoint and ensure 429 responses are handled consistently

FAQ

Should I ever return raw Eloquent models in API responses?

No. Returning raw models risks leaking internal fields and bypasses consistent formatting; always use API Resources or Collections.

When do I choose Sanctum vs Passport?

Use Sanctum for single-page apps and mobile token-based authentication. Use Passport when you need full OAuth2 flows with third-party clients.