La création d'API RESTful est une compétence fondamentale pour le développement web moderne, permettant une communication transparente entre les clients et les serveurs. Flask-RESTX, une extension du framework populaire Flask, simplifie ce processus en fournissant des outils pour créer des API robustes efficacement. Dans ce tutoriel, nous allons explorer comment créer une API RESTful en utilisant Flask-RESTX et démontrer comment la tester avec Apidog, une plateforme intégrée pour la conception d'API, le débogage, la documentation, le mocking et les tests.
1. Introduction aux API RESTful
REST (Representational State Transfer) est un style architectural qui utilise des méthodes HTTP standard pour interagir avec les ressources. Les API qui adhèrent aux principes REST sont appelées API RESTful. Elles fournissent une interface prévisible et uniforme pour les interactions client-serveur, rendant les services web plus accessibles et maintenables.
2. Configuration de votre environnement de développement
Avant de commencer à créer notre API, configurons notre environnement de développement.
Prérequis
Python 3.7 ou supérieur : Assurez-vous que Python est installé sur votre système. Vérifiez en exécutant :
python --version
Environnement virtuel : Il est de bonne pratique de créer un environnement virtuel pour votre projet afin de gérer les dépendances.
python -m venv venv
source venv/bin/activate # Sur Windows: venv\Scripts\activate
Installation de Flask et Flask-RESTX
Avec l'environnement virtuel activé, installez Flask et Flask-RESTX en utilisant pip :
pip install flask flask-restx
Cette commande installe à la fois Flask et Flask-RESTX, ce qui nous permet de créer et de gérer efficacement nos points de terminaison d'API.
3. Installation et configuration de Flask-RESTX
Flask-RESTX est une extension qui ajoute la prise en charge de la création rapide d'API REST avec Flask. Elle encourage les bonnes pratiques avec une configuration minimale.
Installation
Si vous n'avez pas encore installé Flask-RESTX, vous pouvez le faire en utilisant pip :
pip install flask-restx
Configuration
Créez un nouveau fichier Python, par exemple, app.py, et configurez la configuration de base :
from flask import Flask
from flask_restx import Api
app = Flask(__name__)
api = Api(app, version='1.0', title='Sample API',
description='A sample API using Flask-RESTX')
if __name__ == '__main__':
app.run(debug=True)
Ce script initialise une application Flask et l'enveloppe avec une instance d'API Flask-RESTX, fournissant une base pour la création de points de terminaison.
4. Création de votre premier point de terminaison d'API
Créons un point de terminaison simple pour comprendre comment fonctionne Flask-RESTX.
Définition d'un espace de noms
Les espaces de noms dans Flask-RESTX aident à organiser votre API et à empêcher les collisions de noms de points de terminaison.
from flask_restx import Namespace, Resource
ns = Namespace('hello', description='Hello World operations')
Création d'une ressource
Les ressources dans Flask-RESTX correspondent aux points de terminaison et définissent comment les méthodes HTTP sont gérées.
@ns.route('/')
class HelloWorld(Resource):
def get(self):
return {'message': 'Hello, World!'}
Enregistrement de l'espace de noms
Enfin, enregistrez l'espace de noms avec l'API :
api.add_namespace(ns)
Maintenant, lorsque vous exécutez votre application et accédez à http://localhost:5000/hello/, vous devriez voir :
{
"message": "Hello, World!"
}
5. Structurer votre application Flask-RESTX
Au fur et à mesure que votre application se développe, il est essentiel de maintenir une structure propre et organisée.
Disposition recommandée du projet
project/
├── app/
│ ├── __init__.py
│ ├── controllers/
│ │ ├── __init__.py
│ │ └── hello_controller.py
│ ├── models/
│ │ ├── __init__.py
│ │ └── hello_model.py
│ └── services/
│ ├── __init__.py
│ └── hello_service.py
├── run.py
└── requirements.txt
Initialisation de l'application
Dans app/__init__.py :
from flask import Flask
from flask_restx import Api
def create_app():
app = Flask(__name__)
api = Api(app, version='1.0', title='Sample API',
description='A sample API using Flask-RESTX')
from .controllers.hello_controller import ns as hello_namespace
api.add_namespace(hello_namespace)
return app
Dans run.py :
from app import create_app
app = create_app()
if __name__ == '__main__':
app.run(debug=True)
Cette approche modulaire sépare les préoccupations, ce qui rend l'application plus maintenable et évolutive.
6. Mise en œuvre des opérations CRUD
Les opérations CRUD — Créer, Lire, Mettre à jour, Supprimer — sont fondamentales pour le développement d'API. Mettons-les en œuvre pour une simple ressource Item.
Définition du modèle
Dans app/models/item_model.py :
from flask_restx import fields
def get_item_model(api):
return api.model('Item', {
'id': fields.Integer(readOnly=True, description='The unique identifier of an item'),
'name': fields.String(required=True, description='Item name'),
'price': fields.Float(required=True, description='Item price')
})
Mise en œuvre de la ressource
Dans app/controllers/item_controller.py :
from flask_restx import Namespace, Resource, reqparse
from app.models.item_model import get_item_model
ns = Namespace('items', description='Item operations')
item_model = get_item_model(ns)
items = []
item_id_counter = 1
parser = reqparse.RequestParser()
parser.add_argument('name', type=str, required=True, help='Name of the item')
parser.add_argument('price', type=float, required=True, help='Price of the item')
@ns.route('/')
class ItemList(Resource):
@ns.marshal_list_with(item_model)
def get(self):
return items
@ns.expect(item_model)
@ns.marshal_with(item_model, code=201)
def post(self):
global item_id_counter
args = parser.parse_args()
item = {
'id': item_id_counter,
'name': args['name'],
'price': args['price']
}
items.append(item)
item_id_counter += 1
return item, 201
@ns.route('/<int:id>')
@ns.response(404, 'Item not found')
@ns.param('id', 'The item identifier')
class Item(Resource):
@ns.marshal_with(item_model)
def get(self, id):
item = next((item for item in items if item['id'] == id), None)
if item is not None:
return item
ns.abort(404, message="Item not found")
@ns.expect(item_model)
@ns.marshal_with(item_model)
def put(self, id):
item = next((item for item in items if item['id'] == id), None)
if item is not None:
args = parser.parse_args()
item.update({
'name': args['name'],
'price': args['price']
})
return item
ns.abort(404, message="Item not found")
@ns.response(204, 'Item deleted')
def delete(self, id):
global items
item = next((item for item in items if item['id'] == id), None)
if item is not None:
items = [item for item in items if item['id'] != id]
return '', 204
ns.abort(404, message="Item not found")
Dans cette implémentation :
- GET /items/ : Récupère la liste des éléments.
- POST /items/ : Ajoute un nouvel élément.
- GET /items/{id} : Récupère un élément spécifique par ID.
- PUT /items/{id} : Met à jour un élément existant par ID.
- DELETE /items/{id} : Supprime un élément par ID.
Cette configuration fournit une interface CRUD complète pour la gestion des éléments dans votre API.
7. Validation et sérialisation des données avec Flask-RESTX
La validation et la sérialisation des données sont cruciales pour garantir l'intégrité et la cohérence des données traitées par votre API. Flask-RESTX propose des décorateurs et des champs pour faciliter cela.
Utilisation de modèles pour la validation
Définissez un modèle pour spécifier les formats d'entrée et de sortie attendus.
from flask_restx import fields
item_model = api.model('Item', {
'id': fields.Integer(readOnly=True, description='The unique identifier of an item'),
'name': fields.String(required=True, description='Item name'),
'price': fields.Float(required=True, description='Item price')
})
En décorant vos méthodes de ressource avec @ns.expect(item_model), Flask-RESTX validera automatiquement les données JSON entrantes par rapport à ce modèle.
Sérialisation des réponses
Utilisez le décorateur @ns.marshal_with pour formater la sortie en fonction du modèle.
@ns.marshal_with(item_model)
def get(self, id):
# Retrieve and return the item
Cela garantit que les données de réponse adhèrent à la structure spécifiée, favorisant la cohérence dans votre API.
8. Tester les API RESTful avec Apidog
Les tests sont une partie essentielle du développement d'API, garantissant que vos points de terminaison fonctionnent comme prévu. Apidog est un outil complet qui rationalise les tests, la conception et la documentation des API.
Configuration d'Apidog
Télécharger et installer : Téléchargez Apidog gratuitement et suivez les instructions d'installation pour votre système d'exploitation.
Créer un nouveau projet : Lancez Apidog et créez un nouveau projet pour votre API.
Importation de votre spécification d'API
Si vous avez documenté votre API à l'aide d'OpenAPI/Swagger, vous pouvez importer la spécification dans Apidog :
Importer la spécification : Dans votre projet Apidog, sélectionnez l'option d'importation d'une spécification d'API et téléchargez votre fichier OpenAPI.
Explorer les points de terminaison : Apidog analysera le fichier et affichera vos points de terminaison d'API, vos paramètres et vos modèles.
Vous pouvez également concevoir des API à partir de zéro dans Apidog.
Tests des points de terminaison
Sélectionner un point de terminaison : Choisissez le point de terminaison que vous souhaitez tester dans la liste.
Configurer la requête :
- Méthode : Assurez-vous que la méthode HTTP correcte (GET, POST, PUT, DELETE) est sélectionnée.
- Paramètres : Saisissez tous les paramètres de requête ou variables de chemin obligatoires.
- En-têtes : Définissez les en-têtes nécessaires, tels que
Content-Type: application/json. - Corps : Pour les requêtes POST et PUT, fournissez la charge utile JSON.
Envoyer la requête : Cliquez sur le bouton Envoyer pour exécuter la requête.
Examiner la réponse :
(Conseil de pro : Apidog valide automatiquement la réponse de l'API.)
- Code d'état : Vérifiez que le code d'état de la réponse correspond aux attentes (par exemple, 200 pour la réussite, 201 pour la création).
- Corps de la réponse : Vérifiez que les données renvoyées sont correctes et correctement formatées.
- En-têtes : Inspectez les en-têtes de réponse pour obtenir des informations supplémentaires.
9. Génération de la documentation de l'API avec Flask-RESTX
Une documentation complète est essentielle pour toute API, facilitant la facilité d'utilisation et l'intégration pour les développeurs. Flask-RESTX offre une prise en charge intégrée pour la génération d'une documentation d'API interactive.
La génération d'une documentation d'API complète et conviviale est cruciale pour les développeurs et les utilisateurs qui interagissent avec votre API. Flask-RESTX simplifie ce processus en générant automatiquement une documentation Swagger UI, fournissant une interface interactive pour explorer et tester vos points de terminaison d'API.
Documentation Swagger automatique
Par défaut, Flask-RESTX génère une documentation Swagger accessible à l'URL racine de votre API. Cette fonctionnalité offre un aperçu immédiat de la structure de votre API et des points de terminaison disponibles sans configuration supplémentaire.
Personnalisation de la documentation avec des décorateurs
Flask-RESTX fournit plusieurs décorateurs pour améliorer et personnaliser votre documentation d'API :
@api.doc() : Ajoute des informations supplémentaires à vos ressources ou méthodes. Par exemple, pour documenter les paramètres :
@api.route('/my-resource/<id>')
@api.doc(params={'id': 'An ID'})
class MyResource(Resource):
def get(self, id):
return {}
@api.response() : Documente les réponses attendues, y compris les codes d'état et les descriptions :
@api.route('/my-resource/<id>')
class MyResource(Resource):
@api.response(403, 'Not Authorized')
def post(self, id):
api.abort(403)
@api.marshal_with() : Spécifie le modèle de sortie pour une réponse, garantissant un formatage cohérent des données :
@api.route('/item/<int:id>')
class ItemResource(Resource):
@api.marshal_with(item_model)
def get(self, id):
# Retrieve and return the item
@api.expect() : Définit le modèle d'entrée attendu pour les requêtes, facilitant la validation et la documentation :
@api.route('/item')
class ItemResource(Resource):
@api.expect(item_model)
def post(self):
# Handle the post request
Organisation avec des espaces de noms
Les espaces de noms dans Flask-RESTX aident à regrouper les ressources associées, améliorant l'organisation de votre API et de sa documentation.
from flask_restx import Namespace, Resource
ns = Namespace('items', description='Item operations')
@ns.route('/<int:id>')
class ItemResource(Resource):
def get(self, id):
# Retrieve and return the item
En enregistrant l'espace de noms avec l'API, tous les itinéraires et la documentation associés sont regroupés de manière appropriée :
api.add_namespace(ns)
Accéder à l'interface utilisateur Swagger
Une fois votre application Flask-RESTX en cours d'exécution, vous pouvez accéder à l'interface utilisateur Swagger générée automatiquement en accédant à l'URL racine de votre API (par exemple, http://localhost:5000/). Cette interface fournit une exploration interactive de votre API, affichant les points de terminaison disponibles, les entrées attendues et les réponses potentielles.
En tirant parti de ces fonctionnalités, vous vous assurez que votre API est bien documentée, conviviale et facilement compréhensible pour les développeurs et les consommateurs.
10. Améliorer la documentation de l'API avec Apidog
Bien que Flask-RESTX fournisse une documentation de base, Apidog offre des fonctionnalités avancées pour la documentation de l'API, notamment la personnalisation, la génération de code automatisée et les tests en temps réel.
Utilisez l'éditeur visuel d'Apidog pour définir vos points de terminaison d'API, les paramètres de requête et les schémas de réponse. En un seul clic, générez une documentation d'API complète et interactive.
Partagez votre documentation avec les membres de l'équipe ou les partenaires externes, leur permettant de tester les points de terminaison de l'API directement dans la documentation.
En intégrant Flask-RESTX à Apidog, vous pouvez créer des API robustes avec une documentation de qualité professionnelle, améliorant à la fois l'efficacité du développement et l'expérience utilisateur.
Conclusion
Dans ce guide complet, nous avons exploré le processus de création d'API RESTful à l'aide de Flask-RESTX, une extension puissante pour Flask qui rationalise le développement d'API. Nous avons abordé des sujets essentiels tels que la configuration de votre environnement de développement, la création et la gestion des points de terminaison d'API, la validation et la sérialisation des données, et la génération d'une documentation d'API interactive.
De plus, nous avons présenté Apidog, un outil polyvalent qui améliore votre flux de travail de développement d'API en offrant des fonctionnalités telles que les tests automatisés, les tests de performances et la documentation collaborative. En intégrant Apidog à votre processus de développement, vous pouvez vous assurer que vos API sont robustes, efficaces et bien documentées.
