Remplacement de Postman par l’extension de code Visual Studio du client REST / Blogs / Perficient

J’ai (d’une manière ou d’une autre) récemment découvert et commencé à utiliser le Client REST Extension de code Visual Studio créée par Huachao Mao (GitHub : https://github.com/Huachao/vscode-restclient). Il s’agit essentiellement d’un outil de création et d’exécution de requêtes HTTP de type Markdown, intégré à l’éditeur, qui permet aux développeurs de créer une ou plusieurs requêtes dans .http et/ou .rest des dossiers. Considérez-le comme une version plus spartiate et utilitaire de Facteur qui vit juste dans le Code de Visual Studio éditeur. Voici une animation rapide illustrant le processus de rédaction et d’envoi d’une demande simple :

Une requête GET du client REST.

Environnements et variables

La première chose que vous voudrez faire après avoir installé l’extension est de configurer vos environnements et vos variables. L’extension REST Client gère les variables d’environnement (secrètes ou non) d’une manière que je considère élégante, c’est-à-dire n’a pas les gérer du tout (et c’est une bonne chose !) 😉. L’extension extrait les environnements et les variables des paramètres de Visual Studio Code (lire : le settings.json fichier) qui, en fin de compte, est jamais (Est au moins je ne devrais pas jamais) sous contrôle de source ; les développeurs n’ont pas à se soucier de transmettre des secrets au référentiel. Contrairement à Facteur, l’extension REST Client ne se préoccupe pas de la gestion, du stockage ou de la transmission des variables. Certes, il existe un compromis pratique : les développeurs doivent partager leurs variables et leurs secrets à l’aide d’un outil ou d’un service externe. Pour les valeurs sensibles, cela devrait être quelque chose comme Azure Key Vault, CyberArk, etc.

Voici un extrait d’un exemple de code Visual Studio settings.json fichier qui définit quelques variables dans trois environnements différents :

{
  ...
  "rest-client.environmentVariables": {
    "$shared": {
      "shared-variable-1": "foo",
      "shared-variable-2": "buzz",
      "shared-variable-3": "fizz"
    },
    "dev": {
      "variable-1": "foo",
      "variable-2": "buzz",
      "variable-3": "fizz"
    },
    "uat": {
      "variable-1": "foo",
      "variable-2": "buzz",
      "variable-3": "fizz"
    },
    "prd": {
      "variable-1": "foo",
      "variable-2": "buzz",
      "variable-3": "fizz"
    }
  }
  ...
}

Variables définies dans le $shared sont disponibles dans tous les environnements (ou si No Environment est sélectionné comme environnement actuel). Lors de la visualisation d’un .http ou .rest dans l’éditeur, pour basculer entre les environnements, les développeurs peuvent cliquer sur l’environnement actuel dans la barre d’état de Visual Studio Code (en bas à droite, par défaut)…

Barre d’état de Visual Studio Code pour sélectionner l’environnement client REST (dans ce cas, dev est l’environnement actuellement sélectionné).

…ou ils peuvent utiliser le raccourci clavier Ctrl + Alt + E:

Interface Visual Studio Code pour sélectionner un environnement client REST.

Demandes

L’extension prend en charge un large éventail de types de requêtes. Vous pouvez exécuter des requêtes en cliquant sur le Send Request bouton de lien (que l’extension injecte dans l’éditeur, juste au-dessus de la méthode HTTP) ou en utilisant le raccourci clavier Ctrl + Alt + R avec votre curseur positionné dans le bloc de requête (je place généralement mon curseur sur la ligne avec la méthode HTTP). Comme le montre le GIF ci-dessus (oui, c’est un « G » dur, les amis), les réponses apparaissent dans une nouvelle fenêtre côte à côte dans Visual Studio Code. Voici quelques exemples de demandes :

Un simple GET:

# @name get_google
GET https://www.google.com

Un JSON POST à une API de test :

# @name post_test_api
POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

{
    "title": "Test Post",
    "body": "This is a test post.",
    "userId": 123
}

L’extension prend en charge plusieurs requêtes en une seule .http ou .rest déposer. Il est souvent utile de regrouper les requêtes liées et/ou dépendantes dans un même fichier. Considérons cet exemple suivant qui fait un POST demande d’obtenir un jeton d’accès Content Hub, stocke le jeton d’accès dans une variable, puis utilise la variable dans une deuxième requête pour rechercher des ressources dans Content Hub. Notez l’utilisation des variables suivantes (qui, encore une fois, sont stockées dans le fichier settings.json fichier dans une section spécifique à l’extension) :

• contentHubUrl
• contentHubUsername
• contentHubPassword
• clientId
• clientSecret

# @name content_hub_access_token
POST {{contentHubUrl}}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
&username={{contentHubUsername}}
&password={{contentHubPassword}}
&client_id={{clientId}}
&client_secret={{clientSecret}}

###

@content_hub_token={{content_hub_access_token.response.body.access_token}}

# @name get_content_hub_assets
GET {{contentHubUrl}}/api/entities/query?query=Definition.Name=='M.Asset'
Authorization: Bearer {{content_hub_token}}

Lorsqu’elle est exécutée de manière séquentielle, la première requête ensembles le content_hub_token variable et la deuxième requête obtient la variable et utilise la valeur dans son Authorization en-tête pour s’authentifier auprès de Content Hub afin d’extraire les ressources.

Avantages et inconvénients

Je ne peux pas couvrir toutes les fonctionnalités de cette extension dans un seul article de blog : il y en a tout simplement trop 😅. Pour une documentation complète de l’extension client REST, veuillez consulter la page GitHub du projet ici : https://github.com/Huachao/vscode-restclient. Cela dit, voici quelques réflexions supplémentaires (à la fois positives et négatives) après avoir utilisé l’extension sur quelques projets maintenant :

Avantages ✅

• Si Visual Studio Code est déjà votre éditeur de prédilection, alors l’extension REST Client n’est qu’à quelques clics : pas besoin d’installer et d’utiliser une application externe pour envoyer vos requêtes HTTP.
• La syntaxe claire, de type Markdown, pour la création de requêtes est intuitive et conviviale pour les développeurs.
• La possibilité de définir dynamiquement des variables en fonction des réponses et d’utiliser ces variables dans les requêtes en aval permet un chaînage de requêtes puissant.
• Le .http et .rest les fichiers peuvent être validés en toute sécurité dans le contrôle de code source et partagés avec votre équipe de développement.
• La définition et l’échange entre les environnements sont rapides et faciles.
• L’extension affiche des « gribouillis rouges » sous les variables qu’elle ne peut pas résoudre dans un fichier de requête (ce qui signifie généralement que la variable n’est pas définie ou que vous avez sélectionné le mauvais environnement).
• Les réponses sont affichées dans une fenêtre séparée côte à côte et incluent tous les en-têtes et la charge utile de la réponse, le cas échéant (avec des sections réductibles ✨).
• L’extension prend en charge différents types de variables : environnement (y compris partagé), fichier et invite (ce qui signifie que l’extension demande à l’utilisateur de saisir une valeur lorsque la requête est exécutée).
• La prise en charge des raccourcis clavier peut augmenter la productivité des développeurs.

Les inconvénients ❌

• Si vous n’utilisez pas Visual Studio Code, cette extension ne sera pas très utile.
• Au moment de la rédaction de cet article, à ma connaissance, il n’existe aucun moyen d’exécuter plusieurs requêtes en séquence en exécutant simplement la « première » requête : les requêtes doivent être exécutées une par une (et dans le bon ordre, en fonction des paramètres en amont). dépendances).
• Si vous commettez le .http et/ou .rest fichiers pour le contrôle de code source, les autres développeurs de votre équipe auront également besoin que l’extension soit installée.
• Les développeurs doivent partager les variables d’environnement (particulièrement les plus sensibles) en dehors de l’extension (et entièrement en dehors de Visual Studio Code).
• Je n’ai remarqué que cela se produisait lorsque mes charges utiles de réponse étaient assez volumineuses, disons environ 1 Mo (et, en toute honnêteté, cela pourrait être une chose de Visual Studio Code), mais j’ai rencontré des plantages occasionnels de Visual Studio Code en essayant d’envoyer des requêtes ultérieures.

Pensées finales

Les développeurs disposent de nombreuses options (et préférences) lorsqu’il s’agit d’écrire et d’exécuter des requêtes HTTP à des fins de développement ou de test. Pour lister quelques-uns des outils que j’utilise le plus souvent (en plus de l’extension REST Client, bien sûr) : boucle (👴), PowerShell (généralement Invoquer-WebRequest ou Méthode d’appel-Rest), des applications console ponctuelles écrites en C#, Python, etc., et oui, Facteur. Chacun de ces outils a ses mérites et les développeurs doivent utiliser l’outil qui leur convient le mieux, ainsi qu’à leur(s) équipe(s). L’extension REST Client est simplement un autre outil de notre boîte à outils.

Bien que cet article ne concerne pas Postman, je voulais discuter brièvement de la manière dont Postman gère la synchronisation des variables d’environnement et de la façon dont ce processus contraste avec la gestion des variables par l’extension client REST (et rappelez-vous, l’extension n’a pas, gère vraiment les variables autrement que en les lisant à partir des paramètres). Si vous utilisez les fonctionnalités pratiques de synchronisation de l’espace de travail de Postman pour répliquer les variables d’environnement et les requêtes sur différentes machines (et/ou l’interface utilisateur Web de Postman), sachez que, selon la façon dont vous avez configuré vos variables d’environnement, des valeurs sensibles peuvent potentiellement être transmises. sur le fil. Oui, le trafic HTTP est crypté via SSL et, oui, les valeurs sont chiffré au repos sur les serveurs de Postman mais reste-il y a un secret qui « sort du réseau » et qui est stocké par un système tiers 😬. Pour éviter la transmission de secrets, ne le faites pas met le Initial value champ pour les variables, et travaillez exclusivement avec le Current value champ. Les clients Web et de bureau Postman le signalent (sur l’interface de l’environnement ; voir la capture d’écran ci-dessous), mais, sans doute, ce n’est pas aussi évident qu’il devrait l’être pour les développeurs.

Notification des variables sensibles du facteur.

En raison de sa commodité, de sa syntaxe simple, de son utilisation implicite des paramètres de Visual Studio Code pour déléguer la gestion des environnements et des variables et de son ensemble de fonctionnalités globalement riche, j’ai trouvé que l’extension client REST était un excellent outil lorsque vous travaillez avec le API que je rencontre généralement lors de la création d’applications Web modernes. Les solutions Composable Sitecore, par exemple, peuvent impliquer des intégrations avec divers produits Sitecore SaaS, notamment Content Hub, Experience Edge, XM Cloud, XM Cloud Deploy, Sitecore Search, etc. Avoir la possibilité de valider, par exemple, un content-hub.http fichier ou un experience-edge.http fichier au contrôle de code source pour décrire les requêtes et les partager avec votre équipe de développement peut clairement être utile.

Si ce n’est pas déjà fait, allez installer le Client REST extension et vérifiez-le par vous-même ! 👨‍💻