main_backend/.agents/skills/rest-api-best-practices/SKILL.md

name, description

name	description
rest-api-best-practices	Use when designing, reviewing, or changing REST HTTP API routes, request and response shapes, status codes, idempotency, versioning, CORS, or Elysia handlers in this project.

REST API Best Practices

Project Guidance

Treat HTTP semantics as part of the contract. Resource URLs should name things, while methods describe intentions. Keep the local Elysia API predictable for both the renderer and future Tauri callers.

Current routes include /health, /api/status, and /api/echo; preserve simple health/status behavior and use /api/* for application API surface unless the surrounding code establishes otherwise. Use JSON bodies and Elysia validation schemas at route boundaries. Return a consistent error envelope for validation and domain errors.

Prefer least-open CORS. origin: true is acceptable only for local development or clearly trusted callers. For production-facing API behavior, restrict origins to the renderer/Tauri app needs.

Version only when the public contract breaks. Do not add /v2 for additive fields, new endpoints, or internal refactors.

Quick Reference

• GET: transfer the current representation. It is safe and should not mutate server state.
• POST: process the enclosed representation. Use for creation under a collection or workflows where the server chooses the result URI. On successful creation, return 201 Created and Location when a stable resource URL exists.
• PUT: create or replace the target resource state at the request URI. Use when the client knows the target URI and repeated requests should have the same effect.
• PATCH: partial update only when the patch format and merge semantics are explicit.
• DELETE: remove the URI association. Repeated deletes should be safe to retry by outcome.
• 200 OK: successful response with a body.
• 201 Created: new resource created; include Location when applicable.
• 202 Accepted: work accepted but not finished.
• 204 No Content: success with no response body.
• 400 Bad Request: malformed syntax, invalid JSON, framing, or request structure.
• 422 Unprocessable Content: well-formed input that fails schema or semantic validation, when this project chooses to expose that distinction.
• 401: authentication required. 403: authenticated caller lacks permission. 404: resource not found.
• 409: request conflicts with current state.
• 500: unexpected server fault; do not expose internals.

Use idempotency keys for duplicate-prone POST workflows such as purchases, imports, job creation, or retry-heavy Tauri/native operations.

Common Mistakes

• Using verbs in paths like /api/createUser instead of resource paths like /api/users.
• Mutating data in GET handlers.
• Returning 200 for every outcome and hiding failures in JSON fields.
• Creating resources with POST but omitting 201 and Location when the new URL is known.
• Treating POST and PUT as interchangeable.
• Returning different error shapes from validation, auth, and domain logic.
• Adding API versions before there is a breaking contract change.
• Leaving permissive CORS in code intended for non-local use.