AgentSkillsCN

api-conventions

REST路由规范 `/api/v1`、统一的响应契约以及一致的HTTP状态码。关键词：API、REST、路由、状态码、错误契约、分页。

SKILL.md
--- frontmatter
name: api-conventions
description: Conventions de routes REST `/api/v1`, contrats de réponses uniformes et codes HTTP cohérents. Mots-clés: API, REST, routes, status code, error contract, pagination.

Skill: Conventions API

Utilise ce skill quand la tâche porte sur les routes, contrats de réponse, validation et cohérence API.

Quand l’utiliser

  • •Création/édition de routes Express
  • •Standardisation des réponses succès/erreur
  • •Mise en place pagination/meta
  • •Harmonisation des codes HTTP

Standards obligatoires

  • •Préfixe unique: /api/v1
  • •Succès: { success: true, data, meta? }
  • •Erreur: { success: false, error: { code, message } }
  • •Codes usuels: 200, 201, 204, 400, 401, 403, 404, 409, 422, 500

Guidelines

  1. •Valider payload, params et query avec Zod.
  2. •Mapper les erreurs métier vers codes HTTP explicites.
  3. •Pour listes, retourner meta (total, page, perPage).
  4. •Ne jamais exposer stack trace interne en production.
  5. •Conserver des messages d’erreur stables et actionnables.

Exemples de demandes

  • •« Normalise les réponses de tous les endpoints clients »
  • •« Ajoute une pagination standard sur /api/v1/clients »
  • •« Implémente un middleware global de gestion d’erreurs »