I. Introduction▲
Dans cet article, j’explique comment créer une API RESTful en utilisant Flask et comment PyCharm peut vous y aider.
Nous allons utiliser les éléments suivants :
- Flask ;
- Flask-RESTful ;
- PostgreSQL et pgmigrate pour les migrations ;
- l’ensemble Ubuntu, Vagrant, Ansible, comme présenté dans cet article.
Je vous invite à voir ce référentiel GitHub au préalable.
II. L'application : Grouporder▲
Ceux d'entre vous qui travaillent dans un bureau ont déjà été amenés à commander à déjeuner et à partager la commande avec des collègues. De nombreux restaurants ont un montant minimum pour les commandes et il est plus convivial de manger ensemble. De cette façon, si cela finit mal, au moins vous n’êtes pas seul.
Chez JetBrains, nous avons des chaînes Slack qui nous aident à organiser les commandes, et je suppose que beaucoup d’autres sociétés ont quelque chose de similaire. Nous sommes une entreprise de technologie. Nous allons donc aujourd’hui étudier comment résoudre ce type de problème avec du code.
Notre application doit présenter une API REST qui permet de créer une commande de groupe et qui permet ensuite à d’autres utilisateurs d'ajouter ce qu'ils souhaitent à cette commande.
Les routes dont nous aurons besoin :
- /users pour enregistrer des utilisateurs ;
- /users/login pour échanger un nom d'utilisateur et un mot de passe contre un jeton ;
- /restaurants pour connaître les endroits où nous pouvons commander notre repas ;
- /restaurants /
<
id>
/menu pour les plats proposés au menu ; - /orders pour définir les commandes réelles.
III. Le Stack▲
Nous utiliserons Flask avec Flask-restful pour créer notre API. Nous accepterons et renverrons JSON, et Flask-RESTful gère la plupart de ces problèmes pour nous. Pour bien distinguer les choses, nous séparerons la couche API de la couche de données.
La base de données de ce projet sera PostgreSQL, avec laquelle nous communiquerons en utilisant psycopg2 et le langage SQL simple, car nous le pouvons. Si suffisamment de personnes sont intéressées par le sujet, un futur article de blog pourrait plutôt indiquer comment passer à SQLAlchemy. Faites-moi savoir dans les commentaires si vous souhaitez en savoir plus à ce sujet.
Pour mettre à jour notre base de données sans utiliser d’ORM, nous allons utiliser pgmigrate , un outil qui permet d’écrire des scripts de migration en SQL et qui gérera l’exécution des migrations.
Enfin, nous utiliserons Vagrant pour créer automatiquement une machine virtuelle reproductible pour notre développement. Nous utiliserons Ansible pour mettre en service la machine virtuelle. Ainsi, nous pourrons facilement utiliser la même mise en service sur AWS dans un article de blog ultérieur.
IV. Commencer▲
Ouvrez PyCharm et extrayez le référentiel (VCS | Checkout from Version Control | GitHub). Une fois le projet ouvert, exécutez vagrant up (Tools | Vagrant | Up) pour démarrer la VM de développement.
À ce stade, Vagrant téléchargera une boîte de base Ubuntu, telle que configurée dans le fichier Vagrant. Ensuite, la machine virtuelle sera fournie avec Ansible, avec tous les rôles du dossier roles, comme spécifié dans setup.yml. Pour plus de détails, référerez-vous à cet article, publié précédemment sur le blog JetBrains PyCharm.
Lorsque Vagrant a terminé, nous pouvons configurer notre interprète. Aller à Settings | Project Interpreter, utilisez l’icône d'engrenage pour choisir « Add Remote », puis ajoutez un interprète Vagrant, avec /home/vagrant/venv/bin/python comme chemin d’interprète.
Le code Python grouporder est dans un sous-répertoire du référentiel, nous devons donc le dire à PyCharm afin qu'il résolve correctement le code. Faites un clic droit sur le dossier « grouporder », choisissez Mark Directory as | Sources Root.
Avant de pouvoir lancer l’application Flask, il reste encore une chose à régler. Nous devons migrer la base de données. Créons une configuration d’exécution pour cela :
Utilisez la flèche bas pour sélectionner « Nom du module  », puis tapez pgmigrate . Les paramètres sont les suivants : migrate --target latest –conn postgresql://grouporder: hunter2@localhost/grouporder . Enfin, assurez-vous que le répertoire de travail est le dossier de migration. Lorsque vous exécutez cette configuration (avec l’icône de lecture verte), elle ne devrait rien renvoyer et se contenter de dire ‘ Process finished with exit code 0 ’.
Nous pouvons nous assurer que les migrations ont été appliquées en connectant PyCharm à la base de données. Accédez à la fenêtre de l’outil Base de données ( View | Tool Windows | Database ) pour configurer la connexion. Utilisez le « + » vert pour ajouter une nouvelle source de données PostgreSQL. Si PyCharm vous indique qu’il manque un pilote, cliquez simplement sur le lien pour l’installer automatiquement.
Nous avons exposé Postgres sur le port 5678 de l’hôte dans le Vagrantfile afin de pouvoir nous y connecter en utilisant localhost avec ce port. Bien sûr, le mot de passe doit être sûr, pas de mot de passe comme hunter2 :
Après avoir cliqué sur « OK », la base de données apparaît dans la fenêtre d’outils. Si vous développez le nœud « tables » dans le schéma « public », vous devriez voir les tables de notre application :
Si ce n’est pas le cas, assurez-vous que vous êtes bien connecté au port 5678, et non au port 5432 par défaut, il est possible que vous vous connectiez à un serveur postgres s'exécutant localement sur votre système.
V. Lancer l'application▲
Maintenant que toute la configuration est terminée, créons une configuration d’exécution pour notre application et voyons comment elle fonctionne. Allez à Run | Edit Configurations et utilisez le « + » vert pour ajouter une nouvelle configuration d’exécution Python :
Utilisez à nouveau la flèche orientée vers le bas pour passer de « Script path » à « Module name » et définissez flask comme nom de module. Ajoutez ensuite run --host = 0.0.0.0 en tant que paramètres. Toutes les configurations ultérieures sont effectuées avec des variables d'environnement. Utilisez le bouton … à côté du champ des variables d'environnement pour ajouter les variables nécessaires :
La connexion à la base de données est configurée avec une URL postgres: postgres://grouporder: hunter2@localhost/grouporder. Enfin, assurez-vous de cocher la case « Single instance only » dans le coin supérieur droit de la configuration de l’analyse. Nous n’avons qu’un port 5000, nous ne pouvons donc pas exécuter plusieurs instances du même serveur.
Nous pouvons enfin utiliser notre application aux fins prévues. Nous allons configurer un compte utilisateur dans notre application et suivre le processus.
VI. Requêtes HTTP▲
Dans PyCharm 2017.3, nous avons introduit un nouveau client HTTP. Dans le nouveau client, vous pouvez simplement écrire une requête HTTP dans l'éditeur, puis l'exécuter directement à partir de là . Voyons comment cela fonctionne.
Pour créer un compte d'utilisateur, nous devons utiliser POST sur la route / users . Appuyez sur « Ctrl+Alt+Maj+Inser  » (ou Ctrl+N sur macOS) pour créer un fichier de travail, choisissez « Requête HTTP » pour le type de fichier. Ensuite, nous pouvons commencer à écrire la demande :
Après avoir utilisé le bouton vert pour exécuter la demande, nous pouvons voir le résultat dans la fenêtre de l'outil d'exécution. Dans les fichiers de travail, nous pouvons également voir les réponses à nos demandes précédentes, en appuyant sur Ctrl + Clic sur la ligne avec la date et l'heure de la demande.
Maintenant, nous pouvons nous connecter en tant que nouvel utilisateur (nous pouvons écrire une autre demande après la ligne avec « ### »), et nous aurons un jeton :
Au cours de cette session, nous pouvons utiliser ce jeton dans un en-tête d’autorisation pour authentifier nos demandes. Le jeton expire trois heures après sa création (voir data/api/users.py ). Alors, utilisons notre jeton pour essayer de créer un restaurant :
Malheureusement, l’application ne nous le permet pas. Il s'avère qu’il nous faut une autorisation « can_manage_restaurants  » pour apporter des modifications aux restaurants ou aux menus. Et le développeur paresseux de ce programme (qui est ce type de toute façon ?) n’a pas ajouté de voie pour le faire. Modifions cela manuellement dans la base de données.
À ce stade, nous devrions pouvoir accéder à la table users et cocher la case can_manage_restaurants. Double-cliquez sur le champ pour activer la modification, puis cliquez jusqu'à afficher une case à cocher. Ensuite, validez vos modifications dans la base de données en cliquant sur Soumettre (ou en appuyant sur Ctrl+Entrée) :
Une fois la modification effectuée, vous devriez pouvoir ré-exécuter la demande HTTP et obtenir 201 Created . Pour voir le reste des demandes que vous devez effectuer pour ajouter des éléments de menu et créer une commande, consultez le fichier example_requests.http . Tant que vous remplacez les jetons d'autorisation par ceux que vous avez obtenus de la demande de connexion précédemment, vous devriez pouvoir suivre tout le processus en cliquant sur les icônes de lecture vertes dans la gouttière.
VII. Remerciements Developpez.com▲
Developpez.com remercie Ernst Haagsman pour l’autorisation de publications de ce tutoriel. Tous les remerciements aussi à Guillaume SIGUI pour la mise au gabarit et f-leb pour la relecture orthographique.