api-endpoint

name	api-endpoint
description	Use when creating, updating, reviewing, or debugging API endpoints, routes, controllers, services, request validation, responses, or REST/HTTP handlers.

API Endpoint

Use this skill for safe, consistent API endpoint work.

Rules

• Follow the project’s existing framework, folder structure, naming, and API patterns.
• Inspect similar endpoints before creating new code.
• Keep routes/controllers thin.
• Validate untrusted input at the request boundary.
• Put business logic in services, use-cases, or domain modules.
• Keep database access in repositories, models, or data-access modules.
• Do not pass raw request/response objects into business logic.
• Do not add a new validation, auth, API, or database library unless already used or explicitly requested.
• Preserve existing response and error formats.
• Avoid unrelated refactors.

Inspect First

Before changing endpoint code, check existing patterns for:

• route location
• controller/handler style
• validation
• auth and permissions
• service/use-case layer
• data-access layer
• response format
• error format
• tests

Implementation Checklist

• Identify method, path, params, query, body, headers, and context.
• Reuse existing route/controller/service patterns.
• Validate all client-controlled input.
• Apply authentication when required.
• Apply authorization for user-owned, role-based, tenant, or permission-based resources.
• Call service/use-case with validated data and trusted context.
• Keep data access isolated.
• Return only safe response fields.
• Map errors to the project’s existing format.
• Add or update relevant tests.

Security Rules

• Do not trust client-provided IDs, roles, ownership, prices, permissions, tenant IDs, or status values.
• Prevent cross-user, cross-tenant, or cross-organization access.
• Validate sort and filter fields with allowlists.
• Use safe pagination limits.
• Avoid mass assignment by accepting only expected fields.
• Never expose secrets, tokens, stack traces, database errors, or internal details.

Error Defaults

Use project mappings first. If missing:

Case	Status
Invalid input	400
Unauthenticated	401
Forbidden	403
Not found	404
Conflict or duplicate	409
Rate limited	429
Unexpected error	500

Tests

Cover relevant paths:

• success
• validation failure
• unauthenticated
• forbidden
• not found
• conflict/domain error
• data-access failure when relevant
• integration path when multiple layers are affected