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

Pour créer une API REST, établissez la liste des ressources que gère votre app (utilisateurs, commandes, réservations), attribuez à chacune une URL comme /orders et /orders/{id}, puis 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 d'état clairs, validez chaque entrée, exigez une authentification et des vérifications de permission 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 décisions de conception, un ensemble de routes concret, des prompts pour un créateur d'apps 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 app mobile, un partenaire ou un outil d'automatisation doit 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 de requête unique et flexible convient mieux.

Concevoir d'abord : ressources et routes

Écrivez les noms de votre app et ce que les gens font avec eux. Pour une simple app de réservation :

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

• 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 ».
• Un nommage cohérent des champs, comme created_at partout.

Codes d'état 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 seule forme JSON cohérente, par exemple {"error": {"code": "slot_taken", "message": "Ce moment 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, y compris qui peut appeler chacune.
2. Modélisez les données dans votre base de données, avec les champs et les relations nécessaires.
3. Construisez d'abord les routes de lecture, puis celles de création, de modification et de suppression.
4. Validez les entrées sur 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 pas seulement qu'une personne est connectée.
6. Paginez chaque liste et plafonnez la taille des pages.
7. Limitez le débit des connexions et des routes coûteuses. Voir la limitation de débit.
8. Configurez CORS uniquement si des navigateurs d'autres domaines doivent appeler l'API, et listez explicitement ces origines. Corriger les erreurs CORS explique les erreurs que vous verrez.
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 d'apps par IA

Structure de base :

Crée une API REST pour les réservations avec ces routes : GET /api/health, GET /api/bookings (paginée, 50 par page au maximum), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Enregistre 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 en JSON sous la forme {"error": {"code", "message"}} avec les bons codes d'état (400, 401, 403, 404, 409). Garde les secrets dans des variables d'environnement.

Sécurité :

Exige une connexion sur chaque route des réservations. Pour chaque lecture, modification et suppression, vérifie côté serveur que la réservation appartient à l'utilisateur actuel ; renvoie 404 si ce n'est pas le cas. 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 sur le 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 du frontend, car des attaquants le feront :

• Chaque route fonctionne avec des données valides et renvoie la forme et le code documentés
• Les 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 ID 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 débit renvoient 429
• Les réponses d'erreur ne contiennent aucune trace d'appel, aucune requête SQL ni aucun secret
• CORS n'autorise que les origines que vous voulez

Erreurs courantes

• Vérifier la connexion sans vérifier la propriété. La faille la plus fréquente dans une API : n'importe quel utilisateur connecté peut lire n'importe quel enregistrement en changeant l'ID.
• 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 entières de la base de données. Les hachages de mots de passe et les champs internes fuient. Choisissez ce que chaque réponse contient.
• Des listes sans limite. Une seule requête pour chaque enregistrement peut ralentir toute l'app.
• Un 200 OK avec un message d'erreur à l'intérieur. Les clients et la surveillance ne peuvent pas savoir que ça a échoué.
• CORS configuré pour tout autoriser sur une API qui utilise des cookies.
• Aucun contrôle de santé ni aucun journal, si bien que vous apprenez les pannes par les utilisateurs.

Pour une vérification plus large avant le lancement, consultez la liste de contrôle de sécurité pour les apps créées avec l'IA.

Construire une API REST dans Mythex

Vous pouvez demander à Mythex une API dans le cadre de votre app ou comme service distinct. La recette de la documentation backend d'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 autres se publient avec un Dockerfile, et Mythex gère le déploiement depuis Publish (backends d'API). Un projet peut faire tourner un site web et un serveur d'API côte à côte, et vous pouvez basculer entre les deux dans l'aperçu. Conservez 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 exécuter des tâches en arrière-plan.

Questions