Cet article est l'une des courtes notes promises lors de la série d'articles Automation For The Smallest .
Étant donné que la principale façon d'interagir avec le système IPAM est l'API RESTful, j'ai décidé d'en parler séparément.

---

Je rends hommage aux architectes du monde moderne - nous avons des interfaces standardisées. Oui, il y en a beaucoup - c'est un moins, mais ils le sont - c'est un plus.

Ces interfaces ont gagné le nom d'API - Application Programming Interface.

L'une de ces interfaces est l'API RESTful, qui est utilisée pour fonctionner avec NetBox.



Si c'est très simple, l'API fournit au client un ensemble d'outils à travers lesquels il peut gérer le serveur. Et le client peut être essentiellement n'importe quoi: un navigateur Web, une console de commande, une application développée par le fabricant ou toute autre application ayant accès à l'API.

Par exemple, dans le cas de NetBox, vous pouvez y ajouter un nouveau périphérique de la manière suivante: via un navigateur Web, en envoyant une requête curl'om dans la console, utilisez Postman, accédez à la bibliothèque de requêtes en python, utilisez le SDK pynetbox ou accédez à Swagger.

Ainsi, après avoir écrit une seule interface, le constructeur s'affranchit à jamais de la nécessité de convenir avec chaque nouveau client de la manière de la connecter (même si ce n'est qu'un peu rusé).

Table des matières

• REST, RESTful, API
• Structure des messages HTTP
  
  • Ligne de départ
  • Rubriques
  • Le corps du message HTTP
  
  
• Les méthodes
  
  • HTTP GET
  • POST HTTP
  • HTTP PUT
  • PATCH HTTP
  • SUPPRESSION HTTP
  
  
• Façons de travailler avec l'API RESTful
  
  • Curl
  • Facteur
  • Python + Demandes
  • Kit de développement logiciel Pynebtbox
  • Swagger
  
  
• Critique du REST et des alternatives
• Liens utiles

REST, RESTful, API

Ci-dessous, je vais donner une description très simplifiée de ce qu'est REST.

Pour commencer, l' API RESTful est exactement l' interface d' interaction basée sur REST , tandis que REST ( REpresentational State Transfer ) lui-même est un ensemble de restrictions utilisées pour créer des services WEB.

Il est possible de lire exactement quelles limitations peuvent être trouvées dans le chapitre 5 de la thèse de Roy Fielding, Styles architecturaux et conception d'architectures logicielles basées sur le réseau . Permettez-moi de vous donner seulement les trois plus importants (de mon point de vue) d'entre eux:

1. L'architecture REST utilise le modèle d'interaction client-serveur.
2. Chaque demande REST contient toutes les informations nécessaires à son exécution. Autrement dit, le serveur ne doit se souvenir de rien sur les demandes précédentes des clients, qui, comme vous le savez, se caractérise par le mot Stateless - ne stocke pas les informations d'état.
3. Interface unifiée. L'implémentation de l'application est distincte du service qu'elle fournit. Autrement dit, l'utilisateur sait ce qu'il fait et comment interagir avec lui, mais comment il le fait n'a pas d'importance. Lorsque vous modifiez l'application, l'interface reste la même et les clients n'ont pas besoin de s'adapter.

Les services WEB qui satisfont à tous les principes de REST sont appelés services WEB RESTful .

Et l'API qui fournit les services WEB RESTful s'appelle l'API RESTful.

REST n'est pas un protocole, mais le soi-disant style d'architecture (l'un des). Développé avec HTTP par Roy Fielding, REST était destiné à utiliser HTTP 1.1 comme transport.

Adresse de destination (ou en d'autres termes - un objet, ou d'une autre manière - un point de terminaison) - c'est notre URI habituel.

Le format des données transmises est XML ou JSON .

Pour cette série d'articles sur linkmeup, un déploiement en lecture seule a été déployé (pour vous, chers lecteurs). Installation de NetBox: netbox.linkmeup.ru : 45127.

Les droits de lecture ne sont pas requis, mais si vous voulez essayer de lire avec un jeton, vous pouvez utiliser ceci: API de jeton: 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8 .

Faisons une demande de plaisir:

curl -X GET -H "Authorization: TOKEN 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8" \ -H "Accept: application/json; indent=4" \ http://netbox.linkmeup.ru:45127/api/dcim/devices/1/ 

Autrement dit, avec l'utilitaire curl , nous créons un objet GET à netbox.linkmeup.ru : 45127 / api / dcim / devices / 1 / avec une réponse JSON et un retrait de 4 espaces.

Ou un peu plus académiquement: GET renvoie l'objet devices typé, qui est un paramètre de l'objet DCIM .

Vous pouvez également répondre à cette demande - il vous suffit de la copier sur votre terminal.

L'URL à laquelle nous faisons référence dans la demande s'appelle Endpoint . Dans un sens, c'est l'objet final avec lequel nous allons interagir.
Par exemple, dans le cas de netbox, une liste de tous les points de terminaison peut être obtenue ici .

Et faites attention au signe / à la fin de l'URL - il est obligatoire .

Voici ce que nous obtenons en réponse:

 { "id": 1, "name": "mlg-host-0", "display_name": "mlg-host-0", "device_type": { "id": 4, "url": "http://netbox.linkmeup.ru/api/dcim/device-types/4/", "manufacturer": { "id": 4, "url": "http://netbox.linkmeup.ru/api/dcim/manufacturers/4/", "name": "Hypermacro", "slug": "hypermacro" }, "model": "Server", "slug": "server", "display_name": "Hypermacro Server" }, "device_role": { "id": 1, "url": "http://netbox.linkmeup.ru/api/dcim/device-roles/1/", "name": "Server", "slug": "server" }, "tenant": null, "platform": null, "serial": "", "asset_tag": null, "site": { "id": 6, "url": "http://netbox.linkmeup.ru/api/dcim/sites/6/", "name": "", "slug": "mlg" }, "rack": { "id": 1, "url": "http://netbox.linkmeup.ru/api/dcim/racks/1/", "name": "A", "display_name": "A" }, "position": 41, "face": { "value": "front", "label": "Front", "id": 0 }, "parent_device": null, "status": { "value": "active", "label": "Active", "id": 1 }, "primary_ip": null, "primary_ip4": null, "primary_ip6": null, "cluster": null, "virtual_chassis": null, "vc_position": null, "vc_priority": null, "comments": "", "local_context_data": null, "tags": [], "custom_fields": {}, "config_context": {}, "created": "2020-01-14", "last_updated": "2020-01-14T18:39:01.288081Z" } 

Il s'agit de JSON (comme nous l'avons demandé), décrivant l'appareil avec l'ID 1: ce qui est appelé, avec quel rôle, quel modèle, où il se trouve, etc.

Cela ressemblera à une requête HTTP:

  GET /api/dcim/devices/1/ HTTP/1.1 Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4 

La réponse sera donc:

  HTTP/1.1 200 OK Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Jan 2020 15:14:22 GMT Content-Type: application/json Content-Length: 1638 Connection: keep-alive Data 

Videz la transaction .

Voyons maintenant ce que nous avons fait.

---

Structure des messages HTTP

Un message HTTP se compose de trois parties, seule la première est requise.

• Ligne de départ
• Rubriques
• Corps du message

Ligne de départ

Les lignes de départ de la demande et de la réponse HTTP sont différentes.

Requête HTTP

 METHOD URI HTTP_VERSION 

La méthode détermine quelle action le client souhaite effectuer: recevoir des données, créer un objet, le mettre à jour, le supprimer.
URI - l'identifiant de la ressource à laquelle le client accède, ou en d'autres termes, le chemin d'accès à la ressource / au document.
HTTP_VERSION est la version HTTP, respectivement. Aujourd'hui, pour REST, c'est toujours 1.1.

Un exemple:

 GET /api/dcim/devices/1/ HTTP/1.1 

Réponse HTTP

 HTTP_VERSION STATUS_CODE REASON_PHRASE 

HTTP_VERSION - version HTTP (1.1).
STATUS_CODE - trois chiffres du code d'état (200, 404, 502, etc.)
PHASE DE RAISON - Explication (OK, PAS TROUVÉ, MAUVAISE PASSERELLE, etc.)

Un exemple:

 HTTP/1.1 200 OK 

Rubriques

Les en-têtes transmettent les paramètres de cette transaction HTTP.

Par exemple, dans l'exemple ci-dessus dans la demande HTTP, ce sont:

  Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4 

Ils indiquent que

1. Nous nous tournons vers l'hôte netbox.linkmeup.ru:45127 ,
2. La demande a été générée en boucle ,
3. Et nous acceptons les données au format JSON avec une indentation de 4 .

Et voici les en-têtes de la réponse HTTP:

  Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Jan 2020 15:14:22 GMT Content-Type: application/json Content-Length: 1638 Connection: keep-alive 

Ils indiquent que

1. Type de serveur: nginx sur Ubuntu ,
2. Temps de réponse
3. Format des données de réponse: JSON
4. Longueur des données de réponse: 1638 octets
5. La connexion n'a pas besoin d'être fermée - il y aura toujours des données.

Les en-têtes, comme vous l'avez déjà remarqué, ressemblent à des paires nom: valeur, séparées par un signe ":".

Une liste complète des en-têtes possibles .

Le corps du message HTTP

Le corps est utilisé pour transférer les données réelles.

Dans la réponse HTTP, cela peut être une page HTML, ou dans notre cas un objet JSON.

Il doit y avoir au moins une ligne vierge entre les en-têtes et le corps.

Lors de l'utilisation de la méthode GET dans une requête HTTP, il n'y a généralement pas de corps car il n'y a rien à transmettre. Mais le corps est dans la réponse HTTP.

Mais par exemple, avec POST, le corps sera déjà dans la demande. Parlons des méthodes et parlons maintenant.

---

Les méthodes

Comme vous l'avez déjà compris, HTTP utilise des méthodes pour travailler avec les services WEB. Il en va de même pour l'API RESTful.

Les scénarios réels possibles sont décrits par le terme CRUD - Créer, lire, mettre à jour, supprimer .
Voici une liste des méthodes HTTP les plus populaires qui implémentent CRUD:

• HTTP GET
• POST HTTP
• HTTP PUT
• SUPPRESSION HTTP
• PATCH HTTP

Les méthodes sont également appelées verbes , car elles indiquent quelle action est effectuée.

Liste complète des méthodes .

Examinons chacun d'eux en utilisant l'exemple NetBox.

HTTP GET

Il s'agit d'une méthode pour obtenir des informations.

Ainsi, par exemple, nous supprimons la liste des appareils:

 curl -H "Accept: application/json; indent=4" \ http://netbox.linkmeup.ru:45127/api/dcim/devices/ 

La méthode GET est sûre car elle ne modifie pas les données, mais demande uniquement.

Il est idempotent du point de vue que la même requête renvoie toujours le même résultat (jusqu'à ce que les données elles-mêmes aient changé).

Sur GET, le serveur renvoie un message avec le code HTTP et le corps de réponse ( code de réponse et corps de réponse ).

Autrement dit, si tout va bien, alors le code de réponse est 200 (OK).
Si l'URL n'est pas trouvée, 404 (PAS TROUVÉ).
Si quelque chose ne va pas avec le serveur ou les composants eux-mêmes, il peut s'agir de 500 (ERREUR DE SERVEUR) ou 502 (MAUVAISE PASSERELLE).
Tous les codes de réponse possibles .

Le corps est renvoyé au format JSON ou XML.

Videz la transaction .

Donnons quelques exemples supplémentaires. Nous allons maintenant demander des informations sur un appareil spécifique par son nom.

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?name=mlg-leaf-0" 

Ici, pour définir les conditions de recherche dans l'URI, j'ai également spécifié l'attribut de l'objet (le paramètre de nom et sa valeur mlg-leaf-0 ). Comme vous pouvez le voir, avant la condition et après la barre oblique, il y a un "?" et le nom et la valeur sont séparés par un signe "=" .

Voici à quoi ressemble la demande.

  GET /api/dcim/devices/?name=mlg-leaf-0 HTTP/1.1 Host: netbox.linkmeup.ru:45127 User-Agent: curl/7.54.0 Accept: application/json; indent=4 

Videz la transaction .

Si vous devez spécifier quelques conditions, la requête ressemblera à ceci:

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?role=leaf&site=mlg" 

Ici, nous avons demandé tous les dispositifs à feuilles situés sur le site Web de mlg .
C'est-à-dire que les deux conditions sont séparées l'une de l'autre par le signe "&" .

Videz la transaction .

Du curieux et de l'agréable - si à travers "&" vous définissez deux conditions avec le même nom, alors entre elles il n'y aura en fait pas un "ET" logique, mais un "OU" logique.

Autrement dit, une telle requête retournera en fait deux objets: mlg-leaf-0 et mlg-spine-0

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?name=mlg-leaf-0&name=mlg-spine-0" 

Videz la transaction .

Essayons d'accéder à une URL inexistante.

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/IDGAF/" 

Videz la transaction .

---

POST HTTP

POST est utilisé pour créer un nouvel objet dans une collection d'objets. Ou dans un langage plus complexe: pour créer une nouvelle ressource subordonnée.

Clarification d' Arthuriantech :
Y compris, mais sans s'y limiter. La méthode POST est conçue pour transférer des données vers le serveur pour un traitement ultérieur - elle est utilisée pour toutes les actions qui n'ont pas besoin d'être normalisées dans HTTP. Avant la RFC 5789, c'était le seul moyen légal d'apporter des modifications partielles.
roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
tools.ietf.org/html/rfc7231#section-4.3.3

Autrement dit, s'il existe un ensemble de périphériques, alors POST vous permet de créer un nouvel objet de périphérique à l'intérieur des périphériques.

Sélectionnez le même point de terminaison et utilisez POST pour créer un nouveau périphérique.

 curl -X POST "http://netbox.linkmeup.ru:45127/api/dcim/devices/" \ -H "accept: application/json"\ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"name\": \"just a simple russian girl\", \"device_type\": 1, \"device_role\": 1, \"site\": 3, \"rack\": 3, \"position\": 5, \"face\": \"front\"}" 

Un en-tête d' autorisation apparaît déjà ici, contenant un jeton qui autorise la demande d'écriture, et après la directive -d, il y a JSON avec les paramètres du périphérique créé:

 { "name": "just a simple russian girl", "device_type": 1, "device_role": 1, "site": 3, "rack": 3, "position": 5, "face": "front"} 

Votre demande ne fonctionnera pas, car le jeton n'est plus valide - n'essayez pas d'écrire dans NetBox.

La réponse est accompagnée d'une réponse HTTP avec le code 201 (CREATED) et JSON dans le corps du message, où le serveur renvoie tous les paramètres concernant le périphérique créé.

  HTTP/1.1 201 Created Server: nginx/1.14.0 (Ubuntu) Date: Sat, 18 Jan 2020 11:00:22 GMT Content-Type: application/json Content-Length: 1123 Connection: keep-alive JSON 

Videz la transaction .

Maintenant, avec une nouvelle demande avec la méthode GET, vous pouvez la voir dans la sortie:

 curl -X GET -H "Accept: application/json; indent=4" \ "http://netbox.linkmeup.ru:45127/api/dcim/devices/?q=russian" 

"Q" dans NetBox vous permet de trouver tous les objets qui contiennent en leur nom une ligne qui va plus loin.

POST, évidemment, n'est ni sûr ni idempotent - il modifie probablement les données, et une requête à double exécution conduira soit à la création d'une seconde du même objet, soit à une erreur.

---

HTTP PUT

Il s'agit d'une méthode pour modifier un objet existant. Le point de terminaison de PUT est différent de celui de POST - il contient maintenant un objet spécifique.

PUT peut renvoyer les codes 201 ou 200.

Un point important avec cette méthode: vous devez passer tous les attributs requis, car PUT remplace l'ancien objet.

Par conséquent, si, par exemple, en essayant simplement d'ajouter l'attribut asset_tag à notre nouvel appareil, nous obtenons une erreur:

 curl -X PUT "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"asset_tag\": \"12345678\"}" 

 {"device_type":["This field is required."],"device_role":["This field is required."],"site":["This field is required."]} 

Mais si vous ajoutez les champs manquants, alors tout fonctionnera:

 curl -X PUT "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"name\": \"just a simple russian girl\", \"device_type\": 1, \"device_role\": 1, \"site\": 3, \"rack\": 3, \"position\": 5, \"face\": \"front\", \"asset_tag\": \"12345678\"}" 

Videz la transaction .

Faites attention à l'URL ici - elle comprend maintenant l'ID de l'appareil que nous voulons changer ( 18 ).

---

PATCH HTTP

Cette méthode est utilisée pour modifier partiellement la ressource.
Wat? Vous demandez, mais qu'en est-il de PUT?

PUT est une méthode qui existait à l'origine dans la norme, impliquant le remplacement complet d'un objet mutable. En conséquence, dans la méthode PUT, comme je l'ai écrit ci-dessus, vous devrez spécifier même les attributs de l'objet qui ne changent pas.

Et PATCH a été ajouté plus tard et vous permet de spécifier uniquement les attributs qui changent vraiment.

Par exemple:

 curl -X PATCH "http://netbox.linkmeup.ru:45127/api/dcim/devices/18/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" \ -d "{ \"serial\": \"BREAKINGBAD\"}" 

Ici, l'ID du périphérique est également spécifié dans l'URL, mais il n'y a qu'un seul attribut série à modifier.

Videz la transaction .

---

SUPPRESSION HTTP

Supprime évidemment l'objet.

Un exemple.

 curl -X DELETE "http://netbox.linkmeup.ru:45127/api/dcim/devices/21/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" 

La méthode DELETE est idempotente du point de vue qu'une requête répétée ne modifie plus rien dans la liste des ressources (mais renvoie le code 404 (NOT FOUND).

 curl -X DELETE "http://netbox.linkmeup.ru:45127/api/dcim/devices/21/" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: TOKEN a9aae70d65c928a554f9a038b9d4703a1583594f" 

 {"detail":"Not found."} 

---

Façons de travailler avec l'API RESTful

Curl est, bien sûr, très pratique pour les vaillants guerriers CLI, mais il existe de meilleurs outils.

Facteur

Postman vous permet de former des requêtes dans l'interface graphique en sélectionnant les méthodes, les en-têtes, le corps et affiche le résultat sous une forme lisible par l'homme.

De plus, les requêtes et les URI peuvent être enregistrés et leur être retournés ultérieurement.

Téléchargez Postman sur le site officiel .

Nous pouvons donc faire un GET:


Ici, Token est indiqué dans le GET à titre d'exemple uniquement.

Et donc POST:



Postman est destiné à être utilisé avec l'API RESTful uniquement.

Par exemple, n'essayez pas d'envoyer du NETCONF XML à travers lui, comme je l'ai fait à l'aube de ma carrière en automatisation.

L'un des avantages intéressants de l'API spécifiée est que vous pouvez importer tous les points de terminaison et leurs méthodes dans Postman en tant que collection.

Pour ce faire, dans la fenêtre Importer (Fichier-> Importer), sélectionnez Importer depuis le lien et collez dans la fenêtre netbox.linkmeup.ru URL: 45127 / api / docs /? Format = openapi.



De plus, tout ce que vous pouvez trouver se trouve dans les collections.

---

Python + requêtes

Mais même via Postman, vous ne gérerez probablement pas vos systèmes de production. Vous aurez sûrement des applications externes qui voudront interagir avec elles sans votre participation.

Par exemple, un système de génération de configuration souhaite récupérer une liste d'interfaces IP de NetBox.
Python possède une merveilleuse bibliothèque de requêtes qui implémente le travail via HTTP.
Un exemple de demande d'une liste de tous les appareils:

 import requests HEADERS = {'Content-Type': 'application/json', 'Accept': 'application/json'} NB_URL = "http://netbox.linkmeup.ru:45127" request_url = f"{NB_URL}/api/dcim/devices/" devices = requests.get(request_url, headers = HEADERS) print(devices.json()) 

Ajoutez à nouveau un nouvel appareil:

 import requests API_TOKEN = "a9aae70d65c928a554f9a038b9d4703a1583594f" HEADERS = {'Authorization': f'Token {API_TOKEN}', 'Content-Type': 'application/json', 'Accept': 'application/json'} NB_URL = "http://netbox.linkmeup.ru:45127" request_url = f"{NB_URL}/api/dcim/devices/" device_parameters = { "name": "just a simple REQUESTS girl", "device_type": 1, "device_role": 1, "site": 3, } new_device = requests.post(request_url, headers = HEADERS, json=device_parameters) print(new_device.json()) 

---

SDK Python + NetBox

Dans le cas de NetBox, il existe également un SDK Python - Pynetbox , qui représente tous les points de terminaison NetBox en tant qu'objet et ses attributs, faisant tout le sale boulot pour vous de générer des URI et d'analyser la réponse, bien que pas gratuitement, bien sûr.

Par exemple, faisons la même chose que ci-dessus, en utilisant pynetbox.
Liste de tous les appareils:

 import pynetbox NB_URL = "http://netbox.linkmeup.ru:45127" nb = pynetbox.api(NB_URL) devices = nb.dcim.devices.all() print(devices) 

Ajouter un nouvel appareil:

 import pynetbox API_TOKEN = "a9aae70d65c928a554f9a038b9d4703a1583594f" NB_URL = "http://netbox.linkmeup.ru:45127" nb = pynetbox.api(NB_URL, token = API_TOKEN) device_parameters = { "name": "just a simple PYNETBOX girl", "device_type": 1, "device_role": 1, "site": 3, } new_device = nb.dcim.devices.create(**device_parameters) print(new_device) 

Documentation Pynetbox

---

Swagger

Ce qui vaut d'autre grâce à la dernière décennie, ce sont les spécifications de l'API. Si vous suivez ce chemin , vous serez redirigé vers la documentation Swagger UI - Netbox API.



Cette page répertorie tous les points de terminaison, les méthodes de travail avec eux, les paramètres et attributs possibles et indique lesquels sont nécessaires. De plus, les réponses attendues sont décrites.



Sur la même page, vous pouvez effectuer des requêtes interactives en cliquant sur Essayer .

Pour une raison quelconque, swagger prend le nom du serveur sans port comme URL de base, donc la fonction Try it out ne fonctionne pas dans mes exemples Swagger. Mais vous pouvez l'essayer sur votre propre installation.

Lorsque vous cliquez sur Exécuter Swagger, l'interface utilisateur génère une chaîne curl qui peut être utilisée pour effectuer une demande similaire à partir de la ligne de commande.

Dans Swagger UI, vous pouvez même créer un objet:



Pour ce faire, il suffit d'être un utilisateur autorisé disposant des droits nécessaires.

Ce que nous voyons sur cette page est l'interface utilisateur Swagger, une documentation générée sur la base des spécifications de l'API.

Avec les tendances de l'architecture des microservices, il devient de plus en plus important d'avoir une API standardisée pour l'interaction entre les composants, dont les points de terminaison et les méthodes sont faciles à déterminer pour la personne et l'application sans fouiller dans le code source ou la documentation PDF.

Par conséquent, les développeurs suivent aujourd'hui de plus en plus le paradigme API First lorsqu'ils pensent d'abord à l'API, puis seulement à la mise en œuvre.
L'API est d'abord spécifiée dans cette conception, puis la documentation, l'application cliente, la partie serveur sont générées à partir d'elle et des tests sont nécessaires.

Swagger est un langage de cadre et de spécification (qui a maintenant été renommé OpenAPI 2.0), vous permettant de mettre en œuvre cette tâche.
Je n'entrerai pas dans les détails.

Pour plus de détails ici:

• Site Web de Swagger
• Exemple d'utilisation
• Wiki sur Open API

---

Critique du REST et des alternatives

Il y en a un, oui. Tout dans ce monde de l'an 2000 n'est pas déjà si rose.

N'étant pas un expert, je ne prétends pas divulguer de manière substantielle la question, mais je donnerai un lien vers un article incontestable sur Habré .

Une interface alternative pour l'interaction des composants du système est aujourd'hui gRPC. Il a également prophétisé un grand avenir dans le domaine des nouvelles approches de l'utilisation des équipements de réseau. Mais nous parlerons de lui dans le futur, à son tour.

Vous pouvez également jeter un œil au GraphQL prometteur, mais encore une fois, nous n'avons pas besoin de travailler avec lui pour l'instant, il reste donc à étudier de manière indépendante.

---

Est important
Le jeton a9aae70d65c928a554f9a038b9d4703a1583594f a été utilisé à des fins de démonstration uniquement et ne fonctionne plus.

L'indication directe de jetons dans le code du programme est inacceptable et je ne l'ai fait ici que pour simplifier les exemples.

---

Liens utiles

• Le rapport original de Roy Fielding
• API First
• Méthodes HTTP
• Principes REST
• Site Web de Swagger
• Exemple Swagger
• Wiki sur OpenAPI
• Critique de REST

Merci

• Andrei Panfilov pour la relecture et l'édition
• Alexander Fatin pour la relecture et l'édition