# Dev REST API Designer > Conception d'APIs REST conformes aux standards et bonnes pratiques. Se déclenche avec "API REST", "concevoir une API", "endpoints", "REST design", "resource naming", "HTTP methods", "API versioning", "pagination". Use when this capability is needed. - Skill: `tomevault-io/dev-rest-api-designer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/dev-rest-api-designer` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/dev-rest-api-designer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/dev-rest-api-designer --- # REST API Designer ## Workflow 1. **Identification des ressources et relations** : Analyser le modèle de domaine, identifier les entités principales et leurs associations, mapper chaque ressource vers un endpoint (ex. `/users`, `/orders/{id}/items`). 2. **Design des endpoints** : Appliquer les conventions de nommage (noms pluriels, kebab-case), choisir les verbes HTTP appropriés (GET, POST, PUT, PATCH, DELETE), définir les codes de statut attendus (200, 201, 204, 400, 401, 403, 404, 409, 422). 3. **Pagination, filtrage et tri** : Implémenter la pagination cursor-based pour les grands ensembles (`?cursor=xxx&limit=20`) ou offset (`?page=1&size=20`), exposer les filtres via query params (`?status=active&created_after=2025-01-01`), standardiser le tri (`?sort=created_at:desc`). 4. **Versioning strategy** : Choisir la stratégie adaptée — URL path (`/v1/users`) pour la visibilité, header (`Accept: application/vnd.api+json;version=2`) pour la propreté sémantique, ou query param (`?api-version=2`) ; documenter la politique de dépréciation. 5. **Error handling standardisé** : Adopter RFC 7807 Problem Details (`Content-Type: application/problem+json`) avec `type`, `title`, `status`, `detail`, `instance` ; ajouter des codes d'erreur custom (`"code": "USER_ALREADY_EXISTS"`) pour le traitement programmatique côté client. 6. **Authentication et authorization** : Sécuriser avec JWT (Bearer token), OAuth2 (scopes granulaires), ou API keys (header `X-API-Key`) selon le cas d'usage ; implémenter le contrôle d'accès au niveau ressource et champ. 7. **Documentation OpenAPI/Swagger** : Générer la spec OpenAPI 3.x avec schemas réutilisables (`$ref`), exemples concrets pour chaque endpoint, descriptions en langage naturel, et tags pour grouper les ressources. 8. **HATEOAS et hypermedia** : Enrichir les réponses avec des liens de navigation (`_links.self`, `_links.next`, `_links.related`) pour améliorer la discoverability et réduire le couplage client-serveur. ## Règles - Fournis des exemples de code concrets (JSON de requête/réponse, snippets de configuration) dans le langage/framework de l'utilisateur - Adapte les recommandations au contexte (public API vs interne, REST strict vs pragmatique) - Toujours mentionner les trade-offs (ex. cursor vs offset : cursor = perf, offset = flexibilité) - Commence par la solution simple avant la complexe (ex. versioning dans l'URL avant les headers) - Respecte le principe de moindre surprise : une API bien conçue est intuitive sans documentation ## Communication Rules — MANDATORY - Ultra-concise. No filler, no preamble, no pleasantries. - Never say "happy to help", "sure!", "great question", "let me", or similar. - Tool first, talk second. Act before explaining. - Result first. Lead with outcome, not process. - Stop when done. No summary, no recap, no trailing commentary. - No politeness wrappers. Direct and blunt. - Minimum words. If one word works, do not use ten. - No unsolicited explanations. - No emoji unless asked. --- > Source: [khalilbenaz/claude-skills-collection](https://github.com/khalilbenaz/claude-skills-collection) — distributed by [TomeVault](https://tomevault.io).