Méthode HTTP QUERY (RFC 10008)

Dokos supporte désormais la méthode HTTP QUERY, définie dans la RFC 10008. Cette méthode combine les avantages des méthodes GET et POST :

• Sécurité : Comme GET, QUERY est considérée comme une méthode sûre (pas de modification des données côté serveur).
• Corps de requête : Comme POST, QUERY accepte un corps de requête pour transmettre des paramètres complexes.
• Transactions : Toutes les opérations de base de données sont automatiquement annulées après exécution, garantissant qu'aucune modification persistante n'est effectuée.

Cette méthode est particulièrement utile pour les requêtes complexes nécessitant des filtres avancés ou des paramètres structurés, sans risquer de modifier les données.

Cas d'utilisation

La méthode QUERY est idéale pour :

• Requêtes analytiques : Récupérer des données agrégées ou filtrées sans altérer l'état du système.
• Intégrations externes : Interroger Dokos depuis des applications tierces avec des paramètres complexes.
• Tableaux de bord : Charger des indicateurs dynamiques sans déclencher de verrous ou de modifications.

Configuration requise

Pour utiliser la méthode QUERY, votre fonction doit être whitelistée dans Dokos. Voici comment procéder :

1. Whitelister une fonction

Ajoutez le décorateur @frappe.whitelist() à votre fonction Python :

@frappe.whitelist()
def ma_fonction_query(param1, param2):
    # Logique de la fonction
    return frappe.get_all("Client", filters={"territory": param1})

2. Appeler la méthode QUERY

Utilisez la méthode HTTP QUERY avec un corps de requête JSON :

QUERY /api/method/ma_fonction_query HTTP/1.1
Content-Type: application/json

{
    "param1": "France",
    "param2": "2023-01-01"
}

Exemple concret

Scénario : Filtrer les clients par territoire

Fonction Python (dans un fichier .py de votre application) :

@frappe.whitelist()
def get_clients_by_territory(territory):
    """Récupère la liste des clients pour un territoire donné."""
    return frappe.get_all(
        "Client",
        filters={"territory": territory},
        fields=["name", "customer_name", "territory"]
    )

Requête QUERY :

QUERY /api/method/get_clients_by_territory HTTP/1.1
Host: votre-site.dokos.cloud
Authorization: token api_key:api_secret
Content-Type: application/json

{
    "territory": "France"
}

Réponse attendue :

{
    "message": [
        {
            "name": "CUST-00001",
            "customer_name": "Maison Verte SARL",
            "territory": "France"
        },
        {
            "name": "CUST-00002",
            "customer_name": "Bureau Moderne",
            "territory": "France"
        }
    ]
}

Sécurité et permissions

• Permissions : La méthode QUERY respecte les mêmes règles de permissions que les autres méthodes HTTP (GET, POST). Assurez-vous que l'utilisateur a les droits nécessaires pour accéder aux données demandées.
• CSRF : Comme QUERY est une méthode sûre, elle n'est pas soumise aux vérifications CSRF.
• Transactions : Toutes les modifications de la base de données effectuées pendant l'exécution d'une requête QUERY sont automatiquement annulées. Cela garantit que les données restent cohérentes.

Limitations

• Pas de modifications persistantes : Toute création, mise à jour ou suppression de données effectuée dans une fonction appelée via QUERY sera annulée.
• Compatibilité : La méthode QUERY n'est pas encore standardisée. Son comportement peut évoluer dans les futures versions de Dokos.

Bonnes pratiques

1. Utilisez QUERY pour les lectures : Réservez cette méthode aux requêtes qui ne nécessitent pas de modifications persistantes.
2. Optimisez les paramètres : Transmettez uniquement les paramètres nécessaires dans le corps de la requête pour éviter des traitements inutiles.
3. Gérez les erreurs : Comme pour toute API, prévoyez des messages d'erreur clairs pour les utilisateurs finaux.

Diagramme de flux

Voici comment la méthode QUERY est traitée dans Dokos :

      
flowchart TD
    A[Requête QUERY reçue] --> B[Authentification]
    B --> C[Vérification des permissions]
    C --> D[Exécution de la fonction whitelistée]
    D --> E[Annulation des transactions]
    E --> F[Retour des données]

    

Comparaison avec GET et POST

FAQ

Puis-je utiliser QUERY pour créer ou modifier des données ?

Non. Toutes les modifications de la base de données effectuées pendant une requête QUERY sont annulées. Utilisez POST pour les opérations qui nécessitent des modifications persistantes.

Comment gérer les erreurs avec QUERY ?

Les erreurs sont gérées de la même manière que pour les autres méthodes HTTP. Utilisez des codes de statut appropriés (ex: 404 Not Found, 403 Forbidden) et des messages d'erreur clairs dans le corps de la réponse.

QUERY est-elle supportée par tous les clients HTTP ?

La méthode QUERY n'est pas standardisée dans HTTP/1.1 ou HTTP/2. Certains clients ou bibliothèques HTTP peuvent ne pas la supporter nativement. Dans ce cas, vous pouvez utiliser POST avec un en-tête X-HTTP-Method-Override: QUERY comme solution de contournement.

Puis-je utiliser QUERY avec des fichiers joints ?

Non. Comme pour GET, la méthode QUERY ne supporte pas l'envoi de fichiers joints. Utilisez POST pour les requêtes nécessitant des fichiers.