How do I install the API Best Practices skill?

Run npx skillmds@latest add guysilvere/api-best-practices in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is API Best Practices safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with API Best Practices?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is API Best Practices free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published API Best Practices?

guysilvere (@guysilvere) published this skill. Their other Agent Skills are listed on their SkillMD profile.

API Best Practices by guysilvere — Agent Skill

Name: API Best Practices
Rating: 4.2 (5 reviews)
Author: guysilvere

API Best Practices

Guide de conception et d'intégration d'API RESTful — principes REST, sécurité, gestion d'erreur, webhooks, retry, idempotency, pagination, review checklist. À utiliser pour toute conception, intégration ou revue d'API (y compris GeniusPay via api-paiements).

guysilvere Updated Sep 22, 2026

File contents

api-best-practices

Ce que je fais

Référentiel de conception et d'intégration d'API RESTful pour Agence Bulles.

RESTful Design

Ressources au pluriel (/users, /payment_requests) ; méthodes GET/POST/PUT/PATCH/DELETE.
Versioning : /api/v1/ dans l'URL.
Pagination : cursor-based (grandes collections) / offset-limit (petites).
Status codes : 200, 201, 204, 400, 401, 403, 404, 409, 422, 500.

Authentification & sécurité

API Keys : header personnalisé (X-API-KEY) pour les serveurs ; OAuth 2.1 / JWT pour les apps utilisateur.
Jamais de clés en clair : variables d'environnement pour l'application (Coolify en prod, .env.local en dev). {file:...} est réservé aux secrets d'agent OpenCode — ne pas confondre les deux.
Rate limiting : headers X-RateLimit-Remaining, Retry-After.
CORS : origines autorisées explicites en production.
Headers : Strict-Transport-Security, X-Content-Type-Options.

Gestion d'erreur

Structure standard : { "id": "error_code", "message": "...", "extras": "..." } → template assets/templates/error-response.json.
Messages explicites, en français pour l'utilisateur final.
Toujours catcher les erreurs HTTP (timeout, 4xx, 5xx) ; timeout raisonnable 10-30 s.

Webhooks

Signature HMAC vérifiée sur le corps BRUT, comparaison à temps constant ; URLs HTTPS uniquement.
Idempotence garantie EN BASE (contrainte d'unicité sur l'id fournisseur), pas seulement applicative.
2xx seulement après persistance durable ; signature invalide → 4xx ; événement inconnu → 2xx + log.
Ne jamais se fier au payload seul pour une opération financière : re-vérifier via l'API de la source.
Retry : backoff exponentiel + jitter, max 3-5 tentatives.

Retry strategy

Exponential backoff avec jitter ; max 3 tentatives pour les appels API.
Header Idempotency-Key pour les écritures — uniquement si le fournisseur le supporte (à vérifier, ne pas présumer).
Un timeout n'est pas un échec : sur une opération financière, re-vérifier le statut avant de relancer (risque de double débit).
Ne jamais relancer automatiquement une écriture non idempotente.

Review d'API (checklist)

Passer assets/checklists/api-review.md avant chaque mise en production d'un endpoint.

Assets

assets/templates/error-response.json
assets/checklists/api-review.md

---name: api-best-practicesdescription: Guide de conception et d'intégration d'API RESTful — principes REST, sécurité, gestion d'erreur, webhooks, retry, idempotency, pagination, review checklist. À utiliser pour toute conception, intégration ou revue d'API (y compris GeniusPay via api-paiements).license: MIT---# api-best-practices## Ce que je fais- Référentiel de conception et d'intégration d'API RESTful pour Agence Bulles.## RESTful Design- Ressources au pluriel (`/users`, `/payment_requests`) ; méthodes GET/POST/PUT/PATCH/DELETE.- Versioning : `/api/v1/` dans l'URL.- Pagination : cursor-based (grandes collections) / offset-limit (petites).- Status codes : 200, 201, 204, 400, 401, 403, 404, 409, 422, 500.## Authentification & sécurité- API Keys : header personnalisé (`X-API-KEY`) pour les serveurs ; OAuth 2.1 / JWT pour les apps utilisateur.- **Jamais de clés en clair** : variables d'environnement pour l'application (Coolify en prod, `.env.local` en dev). `{file:...}` est réservé aux **secrets d'agent OpenCode** — ne pas confondre les deux.- Rate limiting : headers `X-RateLimit-Remaining`, `Retry-After`.- CORS : origines autorisées explicites en production.- Headers : `Strict-Transport-Security`, `X-Content-Type-Options`.## Gestion d'erreur- Structure standard : `{ "id": "error_code", "message": "...", "extras": "..." }` → template `assets/templates/error-response.json`.- Messages explicites, en français pour l'utilisateur final.- Toujours catcher les erreurs HTTP (timeout, 4xx, 5xx) ; timeout raisonnable 10-30 s.## Webhooks- Signature HMAC vérifiée sur le **corps BRUT**, comparaison à **temps constant** ; URLs HTTPS uniquement.- **Idempotence garantie EN BASE** (contrainte d'unicité sur l'id fournisseur), pas seulement applicative.- **2xx seulement après persistance durable** ; signature invalide → 4xx ; événement inconnu → 2xx + log.- **Ne jamais se fier au payload seul** pour une opération financière : re-vérifier via l'API de la source.- Retry : backoff exponentiel + jitter, max 3-5 tentatives.## Retry strategy- Exponential backoff avec jitter ; max 3 tentatives pour les appels API.- Header `Idempotency-Key` pour les écritures — **uniquement si le fournisseur le supporte** (à vérifier, ne pas présumer).- **Un timeout n'est pas un échec** : sur une opération financière, re-vérifier le statut avant de relancer (risque de double débit).- Ne jamais relancer automatiquement une écriture non idempotente.## Review d'API (checklist)- Passer `assets/checklists/api-review.md` avant chaque mise en production d'un endpoint.## Assets- `assets/templates/error-response.json`- `assets/checklists/api-review.md`

Frequently asked questions