Méthode HTTP QUERY

Dans la version next, Dodock accepte la méthode HTTP QUERY. Comme GET, elle lit des données sans les modifier. Comme POST, elle porte ses paramètres dans le corps de la requête. Utilisez-la pour des filtres longs ou structurés, qui dépassent la taille d'une URL. La méthode est définie par la RFC 10008, « The HTTP QUERY Method » de l'IETF.

Comportement

• Méthode sûre : Dodock classe QUERY avec GET, HEAD et OPTIONS. Il ne valide pas la transaction à la fin de la requête : toute écriture en base est annulée.
• Pas de contrôle CSRF : comme pour GET, Dodock ne demande pas de jeton CSRF.
• Autorisations : les règles sont les mêmes que pour GET. Sur un document, QUERY demande le droit de lecture.

Points d'accès qui acceptent QUERY

Méthodes whitelistées

@frappe.whitelist() sans argument methods accepte GET, POST, PUT, DELETE et QUERY. Si vous limitez les méthodes et que la liste contient GET, Dodock ajoute QUERY.

@frappe.whitelist(methods=["GET"])  # accepte aussi QUERY
def clients_par_territoire(territory: str):
    return frappe.get_list(
        "Customer",
        filters={"territory": territory},
        fields=["name", "customer_name", "territory"],
    )

Exemple

Si la fonction ci-dessus est dans mon_app/api.py :

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

{
    "territory": "France"
}

Réponse (clients fictifs) :

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

Avec curl, utilisez -X QUERY :

curl -X QUERY "https://votre-site.dokos.cloud/api/v2/document/Customer" \
  -H "Authorization: token <api_key>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"territory": "France"}, "fields": ["name", "customer_name"]}'

Comparaison avec GET et POST

Limites

• Certains clients HTTP, proxys et pare-feu ne connaissent pas la méthode QUERY. Testez votre chaîne complète avant de l'utiliser en production.
• QUERY ne sert pas à envoyer des fichiers. Utilisez POST sur /api/method/upload_file.
• Pour modifier des données, utilisez POST, PUT, PATCH ou DELETE.

Voir aussi

• API Rest
• API REST v2