Comment créer une API REST : conception, sécurité et déploiement

Pour créer une API REST, listez les ressources que gère votre application (utilisateurs, commandes, réservations), attribuez à chacune une URL comme /orders et /orders/{id}, et utilisez les méthodes HTTP pour les actions : GET pour lire, POST pour créer, PATCH pour modifier, DELETE pour supprimer. Renvoyez du JSON avec des codes de statut explicites, validez chaque entrée, exigez une authentification et des contrôles d'accès par enregistrement côté serveur, et paginez les listes. Documentez ensuite les points d'accès et déployez l'API derrière HTTPS.

Ce guide couvre les choix de conception, un jeu de routes détaillé, des prompts pour un créateur d'applications par IA et les erreurs qui créent des failles de sécurité. Si les API sont nouvelles pour vous, commencez par ce qu'est une API.

Quand vous avez besoin d'une API REST

• Votre interface web doit enregistrer et charger des données depuis un serveur
• Une application mobile, un partenaire ou un outil d'automatisation a besoin d'accéder à vos données
• D'autres services vous envoient des événements (webhooks)
• Vous répartissez le travail entre une équipe frontend et une équipe backend

REST est le style le plus courant, mais ce n'est pas le seul. REST ou GraphQL explique quand un point d'accès unique à requêtes flexibles convient mieux.

Concevoir d'abord : ressources et routes

Listez les noms de votre application et ce que les utilisateurs font avec eux. Pour une application de réservation simple :

Elles correspondent à créer, lire, modifier et supprimer ; voir ce qu'est le CRUD. Conventions utiles à suivre :

• Des noms au pluriel, sans verbes dans les URL : /bookings, pas /getBookings.
• N'imbriquez qu'un niveau lorsque cela clarifie la propriété : /bookings/{id}/notes.
• Les actions qui ne relèvent pas du CRUD peuvent être des sous-ressources : POST /bookings/{id}/cancel est plus clair qu'un PATCH magique.
• Des noms de champs cohérents, comme created_at partout.

Codes de statut et erreurs

Utilisez les codes HTTP standard pour que les clients sachent ce qui s'est passé sans analyser de texte :

Renvoyez les erreurs dans une structure JSON unique et cohérente, par exemple {"error": {"code": "slot_taken", "message": "Ce créneau n'est plus disponible."}}, et n'incluez jamais de traces d'appel ni d'erreurs de base de données dans les réponses.

Options et compromis

Étape par étape

1. Listez les ressources et les routes comme ci-dessus, en précisant qui peut appeler chacune.
2. Modélisez les données dans votre base avec les champs et les relations nécessaires.
3. Construisez d'abord les routes de lecture, puis la création, la modification et la suppression.
4. Validez les entrées à chaque écriture avec une bibliothèque de schémas : champs obligatoires, types, longueurs, valeurs autorisées. Rejetez les champs inconnus.
5. Ajoutez l'authentification, puis l'autorisation par enregistrement : charger /bookings/42 doit vérifier que la réservation 42 appartient à l'appelant, et non simplement qu'une personne est connectée.
6. Paginez chaque liste et limitez la taille des pages.
7. Limitez le nombre de requêtes sur la connexion et les routes coûteuses. Voir la limitation de débit.
8. Configurez CORS seulement si des navigateurs d'autres domaines doivent appeler l'API, et listez explicitement ces origines. Corriger les erreurs CORS explique les erreurs que vous rencontrerez.
9. Rédigez la documentation et les tests de chaque route, y compris les cas d'échec.
10. Déployez avec les secrets dans des variables d'environnement, HTTPS, des journaux et un contrôle de santé.

Prompts à donner à votre créateur par IA

Squelette :

Crée une API REST pour les réservations avec ces routes : GET /api/health, GET /api/bookings (paginée, 50 éléments maximum par page), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Stocke les données dans notre base de données. Valide les corps de requête avec une bibliothèque de schémas et rejette les champs inconnus. Renvoie les erreurs JSON sous la forme {"error": {"code", "message"}} avec les bons codes de statut (400, 401, 403, 404, 409). Garde les secrets dans des variables d'environnement.

Sécurité :

Exige une connexion sur chaque route de réservations. Pour chaque lecture, modification et suppression, vérifie côté serveur que la réservation appartient à l'utilisateur courant ; renvoie 404 sinon. N'accepte jamais d'identifiants d'utilisateur ni de rôles dans le corps de la requête. Limite POST /api/bookings à 20 par minute et par utilisateur. Journalise les erreurs côté serveur sans renvoyer de traces d'appel.

Documentation :

Rédige une description OpenAPI de ces routes, ainsi qu'un court README avec des exemples de requêtes et de réponses pour chacune.

Tester votre API

Testez depuis l'extérieur de l'interface, car les attaquants le feront :

• Chaque route fonctionne avec des données valides et renvoie la forme et le code documentés
• Des champs manquants ou invalides renvoient 400 avec un message clair
• L'absence de jeton renvoie 401 sur chaque route protégée
• L'utilisateur A qui demande l'enregistrement de l'utilisateur B par son identifiant reçoit 404 ou 403
• Les listes sont paginées ; une valeur limit énorme est plafonnée
• Les créations en double ou en conflit renvoient 409, et non 500
• Les limites de requêtes renvoient 429
• Les réponses d'erreur ne contiennent ni traces d'appel, ni SQL, ni secrets
• CORS n'autorise que les origines prévues

Erreurs courantes

• Vérifier la connexion mais pas la propriété. La faille d'API la plus courante : n'importe quel utilisateur connecté peut lire n'importe quel enregistrement en changeant l'identifiant.
• Faire confiance au client. Les prix, les rôles et les identifiants d'utilisateur envoyés dans le corps de la requête peuvent être modifiés.
• Renvoyer des lignes de base de données entières. Les hachages de mots de passe et les champs internes fuient. Choisissez ce que chaque réponse contient.
• Des listes sans limite. Une requête pour chaque enregistrement peut ralentir toute l'application.
• 200 OK avec un message d'erreur à l'intérieur. Les clients et la supervision ne peuvent pas savoir que cela a échoué.
• CORS configuré pour tout autoriser sur une API qui utilise des cookies.
• Pas de contrôle de santé ni de journaux, si bien que vous apprenez les pannes par vos utilisateurs.

Pour une revue plus large avant le lancement, voir la liste de contrôle de sécurité pour les applications créées par IA.

Construire une API REST dans Mythex

Vous pouvez demander à Mythex une API dans le cadre de votre application ou comme service à part entière. La recette de la documentation backend API REST propose un prompt de départ : nommez votre framework et vos routes, demandez des erreurs JSON claires, gardez les secrets dans des variables d'environnement et incluez un Dockerfile. Les backends conteneurisés en Node, Python, C#, Java et d'autres se publient via un Dockerfile, et Mythex gère le déploiement depuis Publier (backends d'API). Un projet peut faire tourner un site et un serveur d'API côte à côte, et vous pouvez passer de l'un à l'autre dans l'aperçu. Stockez les clés comme secrets du projet, et si l'API a besoin d'une base de données, demandez-la dans le chat. Pour le travail planifié autour de votre API, voir comment lancer des tâches en arrière-plan.

Questions