API RESTful - ch-cbna/geonature GitHub Wiki
REST et SOAP sont des approches différentes de la transmission des données en ligne. Plus précisément, toutes deux définissent la manière de développer des interfaces de programmation d'application (API) qui permettent les échanges de données entre plusieurs applications web. REST (Representational State Transfer) est un ensemble de principes architecturaux. SOAP (Simple Object Access Protocol) est un protocole officiel géré par le W3C (World Wide Web Consortium). La principale différence entre les deux est que SOAP est un protocole, REST non. En général, les API suivent l'approche REST ou SOAP en fonction de leur utilisation et des préférences du développeur.
De nombreux systèmes d'anciennes générations reposent encore sur le protocole SOAP. REST est arrivé plus tardivement et est souvent considéré comme une solution plus rapide pour des scénarios basés sur le web. L'architecture REST offre des performances élevées, ce qui la rend particulièrement demandée pour les appareils mobiles, où la vitesse de téléchargement est importante. REST est un ensemble de recommandations qui permet une mise en œuvre flexible, tandis que SOAP est un protocole avec des exigences spécifiques comme l'envoi de messages au format XML.
Les API REST sont plus légères et donc plus adaptées aux concepts récents tels que l'Internet des objets (IoT), le développement d'applications mobiles et le serverless. Les services web SOAP intègrent des spécifications de sécurité et de conformité des transactions qui répondent aux besoins de nombreuses entreprises, mais qui les rendent également plus lourds. De plus, de nombreuses API publiques, telles que l'API Google Maps, suivent les recommandations REST.
REST est un ensemble de principes architecturaux adapté aux besoins des services web et applications mobiles légers. La mise en place de ces recommandations est laissée à l'appréciation des développeurs.
L'envoi d'une requête de données à une API REST se fait généralement par le protocole HTTP (Hypertext Transfer Protocol). À la réception de la requête, les API développées selon les principes REST (appelées API ou services web RESTful) peuvent renvoyer des messages dans différents formats : HTML, XML, texte brut et JSON. Le format JSON (JavaScript Object Notation) est le plus utilisé pour les messages, car, en plus d'être léger, il est lisible par tous les langages de programmation (en dépit de son nom) ainsi que par les humains. Les API RESTful sont ainsi plus flexibles et plus faciles à mettre en place.
Les principaux composants de l'API REST :
- Client — un client ou un programme lancé du côté de l'utilisateur (sur son appareil) initiant la communication.
- Serveur — un serveur utilisant des API comme accès à ses fonctions et données.
- Ressource — tout contenu (vidéo, texte, image) que le serveur transmet au client.
REST n'est lié à aucune technologie ou plate-forme particulière. Il est indépendant de la langue. Il ne précise pas non plus précisément comment créer l'API. Mais il utilise six contraintes architecturales. L'interface peut être appelée une API REST valide en suivant ces contraintes. Ils décrivent comment le serveur traite les requêtes et y répond.
L'API REST implémente un style d'architecture client-serveur. Les responsabilités du côté serveur et du côté client sont séparées, si bien que chaque côté peut être implémenté indépendamment de l’autre. Le client envoie des demandes de ressources et n'est pas associé au stockage de données. Le stockage des données reste à l'intérieur du serveur. Les serveurs ne sont pas impliqués dans la communication avec l'interface utilisateur. Le client et le serveur évoluent de manière interdépendante. Ce facteur rend le REST encore plus flexible et évolutif.
L'interface uniforme repose sur quatre principes :
-
Identification des ressources. Chaque ressource doit avoir une identification indépendante de l'état des ressources. L'URL agit comme un identifiant.
-
Manipulation des ressources par les méthodes standard. Pour que le client puisse interagir avec les ressources, le protocole applicatif par défaut (HTTP) doit être appliqué pour communiquer avec le serveur, i.e. utiliser les méthodes standard GET, PUT, POST et DELETE.
-
Messages auto-descriptifs. Ces messages contiennent toutes les informations nécessaires au destinataire pour sa compréhension. Aucune information supplémentaire n'est requise dans une documentation ou des messages distincts. Chaque message contient suffisamment d'informations pour que le serveur analyse la demande.
-
L'hypermédia. L'API possède un hypertexte/hypermédia, qui permet au client d'utiliser des hyperliens pour connaître toutes les autres actions disponibles après avoir accédé à une ressource.
Cela signifie que le serveur ne contient aucune donnée sur le client. Toutes les informations nécessaires au traitement de la demande sont incluses dans la demande. Le client stocke toutes les informations de session.
Chaque réponse doit contenir des informations indiquant si elle peut être mise en cache ou non et la période pendant laquelle la réponse peut être mise en cache. S'il peut être mis en cache, alors dans des requêtes similaires, le client peut utiliser les mêmes données sans envoyer de manière répétée des requêtes au serveur. Cela permet d'améliorer les performances et la disponibilité.
un client connecté à une API REST ne peut en général pas distinguer s’il est en communication avec le serveur final ou un serveur intermédiaire. Une architecture REST permet par exemple de recevoir les requêtes sur un serveur A, de stocker ses données sur un serveur B et de gérer les authentifications sur un serveur C. Dans un système en couches, les composants ne peuvent voir que les composants situés aux niveaux les plus proches et ceux avec lesquels ils interagissent.
Il s'agit d'une fonctionnalité facultative permettant aux clients de télécharger et d'exécuter du code.
https://appmaster.io/fr/blog/quest-ce-que-lapi-rest-et-en-quoi-differe-t-elle-des-autres-types
Une méthode HTTP est idempotente si une requête identique peut être faite une ou plusieurs fois de suite avec le même effet, tout en laissant le serveur dans le même état. En d'autres termes, une méthode idempotente ne doit pas avoir d'effets secondaires (sauf dans la tenue de statistiques). Implémentées correctement, les méthodes GET, HEAD, PUT et DELETE sont idempotentes, mais pas la méthode POST. Toutes les méthodes sécurisées sont également idempotentes.
Une méthode HTTP est sécurisée (safe) si elle ne modifie pas l'état du serveur. En d'autres termes, une méthode est sécurisée si elle conduit à une opération en lecture seule.
L'idempotence implique que seul l'état réel du serveur est pris en compte et le code d'état renvoyé par chaque requête peut différer : le premier appel d'un DELETE retournera probablement un code 200, tandis que les lancements successifs retourneront probablement un code 404.
-
GET /pageX HTTP/1.1est idempotente. Appelée plusieurs fois de suite, le client obtient les mêmes résultats :
GET /pageX HTTP/1.1
GET /pageX HTTP/1.1
GET /pageX HTTP/1.1
GET /pageX HTTP/1.1
-
POST /add_row HTTP/1.1n'est pas idempotente ; si elle est appelée plusieurs fois, elle ajoute plusieurs lignes :
POST /add_row HTTP/1.1
POST /add_row HTTP/1.1 -> ajoute une 2nde ligne
POST /add_row HTTP/1.1 -> ajoute une 3ème ligne
-
DELETE /idX/delete HTTP/1.1est idempotente, même si le code d'état renvoyé peut changer entre les demandes :
DELETE /idX/delete HTTP/1.1 -> Retourne 200 si idX existe
DELETE /idX/delete HTTP/1.1 -> Retourne 404 comme il vient d'être supprimé
DELETE /idX/delete HTTP/1.1 -> Retourne 404
https://developer.mozilla.org/fr/docs/Glossary/Idempotent
| Ressource | POST | GET | PUT | DELETE |
|---|---|---|---|---|
| /customers | Créer un client | Récupérer tous les clients | Mettre à jour des clients en bloc | Supprimer tous les clients |
| /customers/1 | Error | Récupérer les détails du client 1 | Mettre à jour les détails du client 1 s’il existe | Supprimer le client 1 |
| /customers/1/orders | Créer une commande pour le client 1 | Récupérer toutes les commandes pour le client 1 | Mettre à jour des commandes en bloc pour le client 1 | Supprimer toutes les commandes pour le client 1 |
https://docs.microsoft.com/fr-fr/azure/architecture/best-practices/api-design
| Code | Signification |
|---|---|
| 200 | OK |
| 301 | L’URL demandée a été déplacée de façon permanente |
| 400 | Bad Request |
| 401 | Non autorisé : le serveur ne donnera pas accès au contenu sans autorisation |
| 403 | Interdit : le serveur ne renverra pas le contenu, quelle que soit l’authentification |
| 404 | Not Found |
| 500 | Internal Server Error |
| 501 | Gunicorn error : must start systemctl |