rest-endpoint-conventions

SKILL.md

---
name: rest-endpoint-conventions
description: Use when adding or modifying a REST endpoint. Enforces the project's auth check, validation, error shape and pagination conventions.
---

# REST endpoint conventions

When adding or modifying a REST endpoint:

1. Auth check FIRST: 401 if unauthenticated, 403 if forbidden — never silently empty.
2. Validate the input with the project's existing validation lib (zod, joi, ...) — do not introduce a new one.
3. Errors return `{ error: "CODE", message: "<human-readable>" }`. Status codes follow REST semantics (400 / 404 / 409 / 422 / 500).
4. List endpoints paginate by default (cursor or offset, match what the project already does).
5. Side effects (emails, webhooks) fire AFTER the DB commit, never inside the transaction.

Tag