Créer API personnalisée avec Flask

Hello 👋🏿, c'est Yémalin🤓. Bienvenue dans cette nouvelle partie de notre série d'articles sur Flask ! Après avoir exploré comment créer rapidement un serveur avec Flask, nous allons maintenant nous concentrer sur un sujet tout aussi passionnant : la création d'une API. Si vous n'avez pas encore lu notre précédent article sur la création d'un serveur avec Flask, je vous invite à le consulter ici. Il vous donnera une base pour comprendre les concepts de base de Flask et vous préparera parfaitement pour cette étape suivante de notre voyage vers la création d'une API.

Notre projet s'appellera Contacts+ et consistera à implémenter une API pour gérer un carnet d'adresses. 🚀🚀🚀

Outils et technologies à utiliser
Mise en place de l'architecture du projet
- Création des différents dossiers pour le projet
Définition des routes et des endpoints
- Explication des routes dans Flask et leur lien avec les endpoints d'une API
- Création des routes pour les différentes fonctionnalités de l'API
Implémentation des fonctionnalités de l'API (CRUD)
- Create
- Read
- Update
- Delete
Tests de l'API
- Utilisation de Postman pour tester l'API
Conclusion
- Récapitulation des principales étapes de création d'une API avec Flask
- Encouragement à explorer davantage les fonctionnalités de Flask et à continuer d'apprendre

#Outils et technologies à utiliser

Dans le cadre de notre projet, nous allons utiliser MongoDB comme base de données et Visual Studio Code comme environnement de développement. Vous avez le choix entre deux options pour la gestion de votre base de données :

Installation locale de MongoDB : Si vous préférez utiliser une base de données MongoDB en local, vous pouvez installer MongoDB sur votre machine. Cela vous permettra de créer et de gérer une base de données directement sur votre ordinateur.
MongoDB Atlas : Si vous souhaitez utiliser une base de données MongoDB en ligne, vous pouvez opter pour MongoDB Atlas. MongoDB Atlas est un service de base de données cloud géré qui vous permet de créer, de configurer et de gérer facilement une base de données MongoDB dans le cloud. Cela vous offre la flexibilité de travailler avec une base de données hébergée en ligne, accessible depuis n'importe quel endroit.

Une fois que vous avez configuré votre base de données MongoDB, il peut être utile d'utiliser un outil pour tester et interagir avec votre API. Postman est un outil populaire et convivial qui vous permet d'envoyer des requêtes HTTP et de visualiser les réponses. Voici comment vous pouvez l'ajouter à votre projet :

Téléchargez et installez Postman : Rendez-vous sur le site officiel de Postman (postman.com) et téléchargez la version appropriée pour votre système d'exploitation. Suivez les instructions d'installation pour installer Postman sur votre machine.

Assurez-vous d'installer les outils nécessaires et de configurer votre environnement de développement en conséquence.

#Mise en place de l'architecture du projet

Nous allons développer un CRUD (Create, Read, Update, Delete) pour gérer un carnet d'adresses de manière simple. Voici les différentes étapes que nous allons suivre.

Dans cette section, nous allons aborder la mise en place de l'architecture de notre projet d'API avec Flask. Une bonne organisation de votre projet est essentielle pour maintenir la clarté et la structure tout au long du développement.

La première étape consiste à créer les différents dossiers & fichiers pour notre projet sur votre machine. Vous pouvez choisir une structure qui vous convient, mais voici une suggestion courante :

contacts+ (dossier principal du projet)
- app.py
- .env (variables d'environnement)
- requirements.txt (dépendances du projet)
- modules
  - contacts
    - interface.py
    - contact.py

Dans votre projet principal "contacts+", vous trouverez le fichier "app.py" qui servira de point d'entrée pour votre application Flask. Ce fichier contiendra le code principal de votre API.

Le dossier "modules" est un sous-dossier de "project" et est destiné à organiser les différentes fonctionnalités ou modules de votre application. Dans notre cas, nous avons un module appelé "contacts".

À l'intérieur du dossier "contacts", vous trouverez deux fichiers :

"interface.py" : Ce fichier contient une classe qui gère la collection de contacts. Cette classe implémente les méthodes CRUD (Create, Read, Update, Delete) pour interagir avec la collection de contacts. Il fournit une interface cohérente pour manipuler les contacts.
"contact.py" : Ce fichier contient les endpoints de votre API. Il utilise l'interface du module "contacts" pour effectuer des opérations sur les contacts, telles que la création, la récupération, la mise à jour et la suppression. Les endpoints définis dans ce fichier correspondent aux différentes actions que vous souhaitez prendre en charge pour votre API.

Cette structure en arborescence vous permet d'organiser votre projet de manière logique et cohérente. Elle facilite la navigation et la localisation des différents fichiers et modules de votre application Flask.Une fois que vous avez créé et organisé les dossiers de votre projet, vous êtes prêt à passer à l'étape suivante.

#Définition des routes et des endpoints

Explication des routes dans Flask et leur lien avec les endpoints d'une API

Dans Flask, les routes jouent un rôle essentiel dans la définition des points d'entrée de votre application Web. Elles permettent de mapper des URL spécifiques à des fonctions de traitement appelées "endpoints". Les endpoints sont responsables de la logique de traitement des requêtes et de la génération des réponses correspondantes.

Lorsque vous définissez une route dans Flask, vous spécifiez l'URL correspondante ainsi que la méthode HTTP associée (par exemple GET, POST, PUT, DELETE, etc.). Lorsque l'application reçoit une requête correspondant à cette URL, Flask recherche la route correspondante et exécute la fonction d'endpoint associée.

Les endpoints d'une API sont des fonctions qui définissent la logique de traitement des requêtes et la génération des réponses. Par exemple, vous pouvez avoir un endpoint qui gère la création d'un nouvel utilisateur, un autre qui récupère la liste des utilisateurs, et ainsi de suite.

Le lien entre les routes dans Flask et les endpoints d'une API se fait en définissant une route spécifique pour chaque endpoint. Lorsqu'une requête est envoyée à une URL correspondant à une route spécifique, Flask identifie cette route et exécute l'endpoint associé.

Par exemple, vous pouvez avoir la route "/contacts" qui est associée à l'endpoint pour récupérer la liste des utilisateurs. Lorsqu'une requête GET est envoyée à l'URL "/contacts", Flask exécute l'endpoint correspondant à cette route et génère la réponse contenant la liste des utilisateurs.

contact_request = Blueprint('contacts', __name__)
@CONTACT_REQUEST.route('/', methods=['GET'])
def allContacts():
    return None

Blueprint...
Dans Flask, les blueprints sont une fonctionnalité puissante permettant d'organiser les routes et les vues d'une application en modules réutilisables. Ils facilitent la découpe de votre application en parties plus petites et autonomes, favorisant ainsi une meilleure organisation et une gestion simplifiée du code. Les blueprints sont particulièrement utiles pour structurer les endpoints d'une API, regroupant les fonctionnalités ou ressources liées au sein d'un même blueprint. Cette approche modulaire offre des avantages tels que la réutilisabilité du code, la gestion des dépendances et la collaboration entre développeurs.

Création des routes pour les différentes fonctionnalités de l'API

Lors de la création d'une API avec Flask, il est nécessaire de définir des routes pour les différentes fonctionnalités que vous souhaitez offrir.

Pour créer une route dans Flask, vous pouvez utiliser le décorateur @app.route() suivi de l'URL correspondante. Mais dans notre cas nous allons utiliser BluePrint pour organiser nos routes dans notre API.

Nous allons créer un objet Blueprint en spécifiant son nom et son import_name. Par exemple, nous pouvons créer un Blueprint pour gérer les fonctionnalités liées aux contacts en utilisant :

Dans le fichier contact.py:

# Les modules utilisés...
from flask import Blueprint, request, jsonify
from bson import ObjectId
# ContactInterface étant l'interface qui nous permettra de gérer notre collection de contacts que nous allons définir dans interface.py
from .interface import ContactInterface

contact_request = Blueprint('contacts', __name__)

Ensuite, nous pouvons définir des routes spécifiques pour ce Blueprint en utilisant le décorateur @contact_request.route(). Par exemple, pour créer une route pour récupérer tous les contacts, nous pouvons utiliser :

@contact_request.route('/contacts', methods=['GET'])

Nous allons en profiter pour implémenter toutes les routes ainsi que les endpoints de notre API de gestion de carnet d'adresses:

Dans le fichier contact.py:

@contact_request.route('/', methods=['GET'])
def get_all_contacts():
    """
    Route pour récupérer tous les contacts
    Méthode : GET
    """
    # Implémentation pour renvoyer tous les contacts

@contact_request.route('/create', methods=['POST'])
def create_contact():
    """
    Route pour créer un nouveau contact
    Méthode : POST
    """
    # Implémentation pour créer un nouveau contact

@contact_request.route('/update', methods=['PUT'])
def update_contact():
    """
    Route pour mettre à jour un contact existant
    Méthode : PUT
    """
    # Implémentation pour mettre à jour un contact existant

@contact_request.route('/delete', methods=['DELETE'])
def delete_contact():
    """
    Route pour supprimer un contact
    Méthode : DELETE
    """
    # Implémentation pour supprimer un contact

@contact_request.route('/<id>', methods=['GET'])
def get_contact_by_id(id):
    """
    Route pour récupérer un contact par son ID
    Méthode : GET
    """
    # Implémentation pour renvoyer un contact spécifique en fonction de son ID

Avant de passer à l'implémentation des endpoints, nous allons d'abord créer l'interface qui nous permettra de gérer notre collection de contacts. Cette interface regroupera les méthodes CRUD (Create, Read, Update, Delete) nécessaires pour interagir avec la collection de contacts.

Dans le fichier interface.py, nous allons définir une classe ContactInterface qui fournira les méthodes pour manipuler les contacts. Voici un exemple de mise en place de cette classe :

import os
from pymongo import MongoClient

class ContactInterface:
    def __init__(self):
        # Établir la connexion à MongoDB
        self.client = MongoClient(os.getenv('DATABASE_URL', None)

        # Accéder à la base de données
        self.db = self.client["contacts+"]

        # Accéder à la collection des contacts
        self.contacts = self.db["contacts"]


    def create_contact(self, data):
        """
            Crée un nouveau contact dans la collection.

            Paramètre :
                - data : un dictionnaire représentant les données du                 nouveau contact.

            Retour :
                - Le résultat de l'opération de création.
        """
        self.contacts.insert_one(data)
        data['_id'] = str(data['_id'])
        return data


    def update_contact(self, filter, updated_contact):
        """
            Met à jour un contact existant dans la collection.

            Paramètres :
                - filter : un dictionnaire représentant le filtre pour trouver le contact à mettre à jour.
                - updated_contact : un dictionnaire représentant les nouvelles données du contact.

            Retour :
                - Le résultat de l'opération de mise à jour.
        """
        result = self.contacts.update_one(filter, {"$set": updated_contact})
        return result

    def delete_contact(self, filter):
        """
            Supprime un contact de la collection en fonction du filtre spécifié.

            Paramètre :
                - filter : un dictionnaire représentant le filtre pour trouver le contact à supprimer.

            Retour :
                - Le résultat de l'opération de suppression.
        """
        result = self.contacts.delete_one(filter)
        return result

    def get_all_contacts(self):
        """
            Récupère tous les contacts de la collection.

            Retour :
                - Une liste contenant tous les contacts.
        """
        # Récupère tous les contacts de la collection
        contacts = list(self.contacts.find())

        # Itère à travers chaque contact récupéré
        for contact in contacts:
            # Convertit l'ObjectId en une chaîne de caractères pour eviter certaines erreur lors du renvoie de réponse
            contact['_id'] = str(contact['_id'])

        # Retourne la liste des contacts modifiée
        return contacts

    def get_contact_by_id(self, filter):
        """
            Récupère un contact par son ID.

            Paramètres :
                - filter : le filtre pour identifier le contact.

            Retour :
                - Le contact correspondant à l'ID spécifié.
        """
        contact = self.contacts.find_one(filter)
        contact['_id'] = str(contact['_id'])
        return contact

Cette classe ContactInterface contient les méthodes nécessaires pour effectuer les opérations CRUD sur la collection de contacts. En créant cette interface, nous nous assurons d'avoir une structure claire et organisée pour gérer nos contacts, ce qui facilitera l'implémentation des endpoints de l'API.

Une fois l'interface prête, nous sommes prêts à implémenter nos endpoints pour notre API de gestion de contacts. Dans l'article suivant, nous explorerons en détail la création de ces endpoints en utilisant l'interface que nous venons de mettre en place. Vous apprendrez comment définir les routes, gérer les requêtes HTTP et les réponses, et interagir avec notre collection de contacts. Restez à l'affût pour la suite de notre tutoriel où nous plongerons dans l'implémentation des endpoints de notre API Flask.

C'était Yémalin👉🏿👈🏿, Allez, tchao ! 🚀🔥

Créez votre propre API en utilisant Flask

#Outils et technologies à utiliser

#Mise en place de l'architecture du projet

#Définition des routes et des endpoints