Python: Création d'une API REST

Comment créer une API REST avec Flask

👋 Bienvenue sur la documentation de Stackhero !

Stackhero propose une solution Python cloud prête à l'emploi qui offre de nombreux avantages, notamment :

  • Déployez votre application en quelques secondes avec un simple git push.
  • Utilisez votre propre nom de domaine et profitez de la configuration automatique des certificats HTTPS pour une sécurité renforcée.
  • Bénéficiez de sauvegardes automatiques, de mises à jour en un clic, ainsi que d'une tarification simple, transparente et prévisible.
  • Profitez d'une performance optimale et d'une sécurité renforcée grâce à une VM privée et dédiée.

Gagnez du temps et simplifiez-vous la vie : il suffit de 5 minutes pour essayer la solution d'hébergement Python cloud de Stackhero !

Cette documentation est un guide accessible aux débutants pour créer une API REST en Python.

Dans cet exemple, nous utilisons Flask, un micro-framework léger et facile à prendre en main qui permet de créer rapidement des applications web.

Prérequis

Avant de commencer, assurez-vous que votre ordinateur dispose des outils suivants :

  1. Python
  2. pip
  3. git
  4. asdf

Si votre environnement de développement n'est pas encore prêt, consultez le guide Development platform pour des instructions détaillées. Vous pouvez aussi utiliser la plateforme en ligne Code-Hero. Code-Hero propose un IDE et un terminal en ligne, avec tous les outils essentiels déjà installés, ce qui vous permet de commencer à coder immédiatement sans aucune installation.

API REST Python exécutée dans Code-Hero, accessible directement depuis le navigateurAPI REST Python exécutée dans Code-Hero, accessible directement depuis le navigateur

Création d'un nouveau projet

La première étape consiste à créer un nouveau dossier de projet. Pour ce guide, nous l'appellerons myRestApi :

mkdir myRestApi
cd myRestApi

Ensuite, définissez la version de Python sur la plus récente disponible avec asdf, puis initialisez le dépôt Git :

asdf install python latest \
  && asdf local python latest

echo "__pycache__/" >> .gitignore

git init
git add -A .
git commit -m "First commit"

Installation de la dépendance Flask

Pour cet exemple, une seule dépendance est nécessaire : Flask.

Flask est un framework web léger qui permet de développer rapidement des applications web. Il est conçu pour être simple et intuitif, afin de faciliter la création et le déploiement de services web. Grâce à la gestion intégrée du routage, du templating et des requêtes HTTP, Flask est un excellent choix pour créer des APIs REST.

Installez Flask (et python-dotenv) avec pip :

pip install Flask python-dotenv

Nous installons ici les modules Flask et python-dotenv. Vous verrez bientôt pourquoi nous utilisons python-dotenv (indice : il sert à gérer les variables d'environnement).

Après l'installation, figez les versions des packages dans un fichier requirements.txt :

pip freeze > requirements.txt

Figer vos dépendances garantit que votre serveur de production ou vos collègues utilisent les mêmes versions que vous. Quelques secondes suffisent pour éviter de nombreux problèmes à l'avenir.

Implémentation de l'API REST avec Flask

Passons maintenant au code !

Créez un fichier nommé app.py et insérez le code suivant :

import os
from dotenv import load_dotenv
from flask import Flask, jsonify, request

# Charger les variables d'environnement depuis le fichier .env en dehors de la production
if os.environ.get('ENV') != 'production':
    load_dotenv()

# Créer l'application Flask
app = Flask(__name__)

# Jeu de données exemple
tasks = [
    {
        'id': 1,
        'title': 'Buy groceries',
        'description': 'Milk, Cheese, Pizza, Fruits',
        'done': False
    },
    {
        'id': 2,
        'title': 'Learn Python',
        'description': 'Learn Python programming basics',
        'done': False
    }
]

# Route '/api/tasks' (GET) pour lister toutes les tâches
@app.route('/api/tasks', methods=['GET'])
def get_tasks():
    return jsonify({'tasks': tasks})

# Route '/api/tasks/<task_id>' (GET) pour obtenir une tâche spécifique par son ID
@app.route('/api/tasks/<int:task_id>', methods=['GET'])
def get_task(task_id):
    task = [task for task in tasks if task['id'] == task_id]
    if len(task) == 0:
        return jsonify({'error': 'Task not found'}), 404
    return jsonify({'task': task[0]})

# Route '/api/tasks' (POST) pour créer une nouvelle tâche
@app.route('/api/tasks', methods=['POST'])
def create_task():
    if not request.json or 'title' not in request.json:
        return jsonify({'error': 'Title is required'}), 400
    task = {
        'id': tasks[-1]['id'] + 1,
        'title': request.json['title'],
        'description': request.json.get('description', ""),
        'done': False
    }
    tasks.append(task)
    return jsonify({'task': task}), 201

# Démarrer le serveur API
if __name__ == '__main__':
    if os.environ.get('ENV') == 'production':
        app.run()
    else:
        app.run(host='0.0.0.0', port=8080, debug=True)

Pour démarrer le serveur, exécutez :

python app.py

Avec l'option host='0.0.0.0', vous pouvez également accéder à votre API via votre navigateur lorsque vous utilisez Code-Hero. Rendez-vous simplement sur http://<XXXXXX>.stackhero-network.com:8080/api/tasks, en remplaçant <XXXXXX> par votre domaine Code-Hero.

Tester votre API REST

Une fois le serveur lancé, vous pouvez interagir avec lui en utilisant cURL. Voici quelques exemples :

  • Récupérer toutes les tâches :

    curl -s http://localhost:8080/api/tasks
{
  "tasks": [
    {
      "description": "Milk, Cheese, Pizza, Fruits",
      "done": false,
      "id": 1,
      "title": "Buy groceries"
    },
    {
      "description": "Learn Python programming basics",
      "done": false,
      "id": 2,
      "title": "Learn Python"
    }
  ]
}

  • Récupérer la tâche avec l'ID 2 :

    curl -s http://localhost:8080/api/tasks/2
{
  "task": {
    "description": "Learn Python programming basics",
    "done": false,
    "id": 2,
    "title": "Learn Python"
  }
}

  • Créer une nouvelle tâche :

    curl -s -X POST -H "Content-Type: application/json" \
-d '{"title": "New task", "description": "Created with cURL"}' \
http://localhost:8080/api/tasks
{
  "task": {
    "description": "Created with cURL",
    "done": false,
    "id": 3,
    "title": "New task"
  }
}

Astuce : Passez la sortie à jq pour formater le JSON. Par exemple, curl -s http://localhost:8080/api/tasks/2 | jq affiche un résultat plus lisible.

Exemple d'API REST Python avec Flask, exécutée dans Stackhero Code-Hero, avec le serveur (1) et le client utilisant cURL (2)Exemple d'API REST Python avec Flask, exécutée dans Stackhero Code-Hero, avec le serveur (1) et le client utilisant cURL (2)

Gestion des variables d'environnement

Les variables d'environnement sont essentielles pour protéger les informations sensibles, comme les identifiants de base de données ou les clés d'API. Utiliser des variables d'environnement présente deux avantages principaux :

  1. Vos secrets ne sont pas stockés dans votre dépôt Git, ce qui garantit que des personnes non autorisées ne pourront pas accéder à vos données sensibles même si elles obtiennent votre code source.
  2. Vous pouvez utiliser des identifiants différents selon l'environnement (par exemple, production ou développement).

Pour gérer les variables d'environnement, nous utilisons le module python-dotenv. Installez-le si ce n'est pas déjà fait :

pip install python-dotenv
pip freeze > requirements.txt

Ensuite, créez un fichier .env à la racine de votre projet et ajoutez-y vos variables d'environnement de développement. Par exemple :

ENV="development"
DATABASE_PASSWORD="secretPassword"
THIRD_API_PRIVATE_KEY="secretKey"

Enfin, ajoutez le fichier .env à votre .gitignore pour garantir la sécurité :

echo ".env" >> .gitignore

Pour accéder à ces variables d'environnement en Python, utilisez simplement os.environ.get() :

import os

print(os.environ.get('ENV'))

Le fichier .env est utilisé uniquement pour l'environnement de développement. Pour le staging ou la production, définissez les variables d'environnement dans le tableau de bord Stackhero, dans la configuration de votre service Python.

Préparer Python et Flask pour la mise en production

Ce guide utilise le serveur de développement intégré de Flask, mais pour la production il est indispensable d'utiliser un serveur WSGI adapté comme Gunicorn. Voici les étapes à suivre :

  1. Installez Gunicorn :

    pip install gunicorn
pip freeze > requirements.txt

  2. Lancez votre application avec Gunicorn en utilisant l'argument app:app (le premier app est le nom du fichier, le second est l'instance Flask) :

    ENV=production gunicorn app:app \
  --error-logfile - \
  -b 0.0.0.0:8080

  3. Créez un Makefile pour faciliter le passage entre les modes développement et production :

    .DEFAULT_GOAL := dev

# Par défaut, Stackhero for Python exécute la règle "run". Nous la redéfinissons pour lancer la règle 'prod'.
run: prod

prod:
	ENV=production gunicorn app:app \
	  --error-logfile - \
	  -b 0.0.0.0:8080

dev:
	python app.py

Vous pouvez lancer votre serveur en mode développement avec make dev (ou simplement make), et en mode production avec make prod.

Déployer votre code Python en production

La façon la plus simple de déployer votre projet Python est d'utiliser le service d'hébergement cloud Stackhero Python cloud hosting service. Les principales fonctionnalités sont :

  • Déploiement par simple git push
  • Domaine personnalisable avec gestion automatique des certificats TLS (HTTPS)
  • Exécution sur une VM privée et dédiée pour une sécurité maximale
  • Prise en charge de HTTP/2, TLS 1.3 (HTTPS), WebSockets, compression GZIP & Brotli, ETag, et accès aux ports TCP/UDP

Configuration du service "Stackhero for Python"

Pour déployer votre code sur Stackhero, suivez ces étapes :

  1. Récupérez votre clé publique avec :

    cat ~/.ssh/id_*.pub

  2. Dans le tableau de bord Stackhero, accédez à votre service "Stackhero for Python" et cliquez sur le bouton "Configurer".

  3. Copiez la clé publique obtenue à l'étape précédente et collez-la dans le champ "Clés publiques SSH" ou "Key".

  4. Validez la configuration en cliquant sur le bouton "Valider" en bas de la page.

Configuration de la clé publique "Stackhero for Python"Configuration de la clé publique "Stackhero for Python"

Vous n'avez pas de clés SSH ? Créez-les avec :

ssh-keygen -t ed25519

Enfin, configurez votre dépôt pour déployer sur Stackhero. Dans votre dossier de projet, ajoutez un remote Git avec la commande fournie dans votre service Stackhero (remplacez <XXXXXX> par le domaine de votre service) :

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Commande Git remoteCommande Git remote

Déployer en production

Une fois tout configuré, déployez votre code en production avec une seule commande :

git push stackhero main

Pensez à ajouter et valider vos modifications avant de pousser votre code en production. Dans Stackhero Code-Hero, vous pouvez rapidement valider vos changements via la Command Palette (appuyez sur Ctrl+Shift+P sous Windows/Linux ou Cmd+Shift+P sur macOS et tapez Git: Commit).

Après le déploiement, rendez-vous sur l'URL de votre API à l'adresse https://<XXXXXX>.stackhero-network.com/api/tasks (remplacez <XXXXXX> par le domaine de votre service) pour voir votre API Flask en action.

Conclusion

En suivant ce guide, vous savez maintenant comment créer une API REST avec Flask. Avec ces connaissances, vous pouvez développer et faire évoluer vos applications RESTful en toute confiance, et les intégrer à différents services front-end et back-end.

Autres articles pour Python

  1. Plateforme de développement
    Préparez votre plateforme de développement pour une expérience agréable et efficace
  2. Apprendre Python
    Un guide Python complet
  3. Déployer en production
    Comment déployer votre code Python en production en quelques minutes
  4. Déployer avec GitHub Actions
    Comment déployer votre code Python avec GitHub Actions
  5. Usages avancés
    Aller plus loin avec vos déploiements Python
  6. Dépannage
    Vous rencontrez un problème avec votre service Python ? La solution se trouve probablement ici !
  7. TL;DR
    Etapes pour déployer votre code Python sur Stackhero