laraveldaily/ai-workflows-for-laravel/laraveldaily-api-audit

Laravel API Audit

Analyze a Laravel API project's code against proven API development practices. Scan the relevant PHP source files (excluding vendor/, node_modules/, storage/) and produce a structured report of findings with actionable suggestions.

This is NOT a security audit and NOT a general Laravel structure audit. Focus on API-specific behavior: contracts, JSON responses, validation, error handling, authentication, performance, testing, and route design.

Before You Flag Anything

Read enough of the codebase to understand the project context first:

• Check composer.json and core bootstrapping to confirm the Laravel version and installed packages
• Detect how the API is mounted: routes/api.php, routes/web.php, custom route files, or routes loaded from bootstrap/app.php
• Detect the authentication approach before judging auth code: Sanctum, Passport, JWT, session/cookie auth, custom tokens, or no auth
• Check route groups and global middleware before flagging individual routes
• Check exception rendering and middleware before flagging controller-level JSON issues
• Distinguish public APIs, internal APIs, SPA backends, mobile backends, and webhook-only APIs

Present findings as suggestions, not mandates. API design involves trade-offs, and intentional consistency matters.

What to Check

1. Missing API Resources or Unclear Response Transformation

Scan controllers for raw model responses or hand-built transformations that make the API contract hard to control.

Why it matters: Returning raw Eloquent models or manually transforming arrays across many endpoints makes the contract harder to reason about and easier to break accidentally. API Resources centralize transformation and help control exposed fields.

What to flag:

• return $model, return Model::all(), or similar raw model returns when that exposes unstable or internal fields
• response()->json([...]) with repeated hand-built field mapping across multiple endpoints
• ->toArray() with manual field picking or transformation in controllers
• The same model returned from multiple endpoints with inconsistent field selection
• Relationships accessed in Resources without whenLoaded() when that risks lazy loading or accidental exposure

Suggestion: Use API Resources when the response shape needs to be controlled, reused, or kept consistent. Define explicit fields in toArray(), use ResourceClass::collection(), and prefer $this->whenLoaded() for relationships. Separate Resources for index vs show endpoints can be reasonable.

Exceptions:

• A trivial endpoint like ['status' => 'ok'] does not need a Resource
• A small internal API with intentionally simple raw JSON is not automatically wrong
• Do not flag raw model returns if the model clearly hides sensitive fields and the project uses that pattern consistently

2. Incorrect or Inconsistent HTTP Status Codes

Scan controller return statements and exception handling for missing or semantically misleading HTTP status codes.

Why it matters: API consumers rely on status codes to understand outcomes without inspecting every response body. Incorrect codes make error handling brittle and reduce interoperability.

What to flag:

• Create endpoints returning 200 when the API clearly treats the operation as resource creation and returns the created entity
• Validation or business-rule failures returned as 200 with an error payload
• Server exceptions caught and returned as 200 with patterns like 'success' => false
• Delete endpoints returning a success body with 200 when the rest of the API consistently uses 204, or vice versa
• Mutation endpoints with inconsistent status code conventions across similar controllers

Suggestion: Prefer semantically correct and consistent status codes:

• 200 for successful reads and many updates
• 201 for successful creation when a new resource is created
• 204 for successful delete or update with no body
• 422 for validation failures
• 404 for not found
• 401/403 for authentication/authorization failures
• 429 for throttling

Exceptions:

• 200 on update or delete is not automatically wrong if the endpoint intentionally returns a response body
• Judge consistency within the same API before suggesting changes

3. Inconsistent JSON Response Structure

Scan API controllers, Resources, and exception responses for inconsistent response shapes across the same API surface.

Why it matters: When similar endpoints return different JSON structures without a clear reason, consumers need custom parsing logic and the API becomes harder to use.

What to flag:

• Some endpoints return { "data": ... } while similar endpoints return bare arrays or custom top-level keys for no clear reason
• Success responses mix incompatible conventions such as "success": true, bare arrays, and Resource responses across the same API
• Error responses vary arbitrarily between { "error": ... }, { "message": ... }, and custom shapes without a consistent pattern
• Pagination metadata is custom in some places and standard Laravel links / meta in others

Suggestion: Pick one response convention per API surface and apply it consistently. Laravel API Resources are a simple default, but intentional alternatives are valid too. For errors, prefer one predictable structure and let Laravel's exception handling do most of the work when possible.

Exceptions:

• Do not force a data wrapper if the project intentionally uses bare JSON or a spec like JSON:API
• Do not compare unrelated surfaces such as public API vs admin AJAX vs web responses

4. API Endpoints Returning HTML Error Pages

Scan API routes, middleware, and exception rendering for cases where API consumers may receive HTML instead of JSON.

Why it matters: API clients expect machine-readable errors. HTML error pages are difficult to parse and often indicate that API error handling is not wired consistently.

What to flag:

• API routes that can reach the default HTML exception renderer without JSON expectations being established
• Custom exception handling that renders HTML for routes that are clearly part of the API
• Not-found or authorization failures that leak framework/model internals in the response body
• Tests or code paths showing API endpoints require an Accept: application/json header to avoid HTML, with no project-level handling

Suggestion: First check whether the project already solves this globally through route groups, middleware, or exception rendering. If not, suggest a project-level solution: a middleware that ensures JSON expectations for API routes, exception rendering based on route patterns, or feature tests that assert JSON for API failures.

Important: Do not prescribe one exact fix. The goal is consistent JSON errors for API clients, not a specific middleware implementation.

5. N+1 Queries and Missing Eager Loading

Scan controllers and Resources for relationship access without matching eager loading.

Why it matters: Collection endpoints amplify N+1 problems quickly. APIs often serialize relationships, so missed eager loading can turn one request into dozens of queries.

What to flag:

• Queries using all(), get(), or paginate() without with(...) when the response accesses relationships
• Resources using $this->relation->field directly instead of safer conditional loading patterns
• Nested relationship access in Resources without matching eager loading in the caller
• Controllers eager loading some but not all relationships needed by the Resource

Suggestion: Pair Resource relationship access with controller-level eager loading. Use with() / load() in the query layer and whenLoaded() in Resources to avoid accidental lazy loading.

Exceptions:

• Do not flag single-record endpoints unless the relationship access is clearly expensive or repeated
• Do not flag relation access that is intentionally lazy and only used in a narrow non-collection path

6. Missing or Weak Validation on Write Endpoints

Scan POST, PUT, PATCH, and other write endpoints for missing validation or unsafe data handling.

Why it matters: API clients can send arbitrary payloads. Without validation, bad input can cause SQL exceptions, silent bad data, or unstable API behavior.

What to flag:

• Model::create($request->all()), $model->update($request->all()), or similar mass assignment from unvalidated input
• Write endpoints using request input directly with no validation layer
• Large inline validation blocks in controllers that would be clearer as Form Requests
• Repeated validation logic across multiple endpoints
• File uploads with weak or missing file validation

Suggestion: Use Form Requests for non-trivial validation, access clean data through $request->validated(), and keep validation consistent across similar endpoints.

Exceptions:

• Small inline validation in a simple internal endpoint can be acceptable
• Do not flag $request->validate([...]) automatically; flag it when it becomes large, repeated, or mixed with other controller concerns

7. Unsafe Filtering, Sorting, and Query Parameters

Scan endpoints that accept query parameters for filtering, sorting, includes, pagination, or search.

Why it matters: APIs often expose dynamic query controls. Without validation or whitelisting, these endpoints become fragile, inconsistent, and prone to invalid SQL or accidental data exposure.

What to flag:

• orderBy($request->sort, $request->direction) without whitelisting allowed columns and directions
• Unvalidated per_page, page, include, filter, or search parameters used directly in queries
• Conditional query logic spread across controllers with no normalization or validation
• Arbitrary relation includes with no allowlist

Suggestion: Validate query parameters with a Form Request or explicit validation, whitelist sortable/filterable fields, cap per_page, and centralize query shaping when it becomes complex.

8. Route Model Binding Not Used Where It Would Simplify the API

Scan API controllers for manual lookups from route parameters when implicit binding would make the code clearer and more consistent.

Why it matters: Route model binding reduces boilerplate and standardizes not-found behavior, but it is not appropriate for every query.

What to flag:

• Model::find($id), findOrFail($id), or equivalent boilerplate where the route parameter maps directly to a model
• Manual 404 JSON responses for simple primary-key lookups
• Inconsistent use of route model binding across otherwise similar endpoints

Suggestion: Type-hint the model in the controller signature when the lookup is straightforward. Use custom route keys for slugs where appropriate.

Exceptions:

• Do not flag custom queries that intentionally enforce tenant scoping, ownership, published-only visibility, or nested constraints
• Do not force binding when the controller needs query customization beyond a simple route lookup

9. Missing Transactions on Multi-Step Writes

Scan write endpoints and action/service classes for multi-step mutations without transactional boundaries.

Why it matters: Many API endpoints create or update several records, attach relations, move files, or dispatch side effects. Without a transaction, partial writes leave the system inconsistent when one step fails.

What to flag:

• Create/update flows that write multiple models without DB::transaction()
• Endpoints that create a record and then sync/attach related records with no transactional protection
• Balance/inventory/status changes spread across several writes
• Deleting records plus related cleanup where a failure could leave orphaned state