Frappe Framework
API REST
La liste filtre, trie et pagine. Créer, lire, modifier et supprimer passent par le nom du document. Une méthode en liste blanche s’appelle sous /api/method.
Authentification
Deux voies, plus le jeton d’accès. Le jeton d’API est détaillé dans Authentification par jeton. OAuth est dans Configurer OAuth 2.
Jeton : ouvrir l’utilisateur, onglet Settings s’il y a des onglets, section API Access, Generate Keys. Copier l’API Secret. L’API Key est sur la fiche. L’en-tête est Authorization: token api_key:api_secret. L’exemple interroge frappe.auth.get_logged_user. Chaque appel est journalisé sur cet utilisateur, et ses rôles s’appliquent. On peut créer un utilisateur rien que pour l’API.
Mot de passe : cookie de session. POST /api/method/login, JSON usr et pwd. La réponse d’exemple : message Logged In, home_page /app, full_name, dashboard_route /sites. Le curl publié a des guillemets incohérents dans --data-raw. Le cookie snowcookie sert ensuite à get_logged_user, qui renvoie le nom. Si la bibliothèque ne garde pas la session, utiliser le jeton.
Bearer : Authorization: Bearer access_token sur le même get_logged_user.
Liste
GET /api/resource/:doctype. Vingt enregistrements, seulement le name, sous data. L’exemple est ToDo. Les réponses publiées s’interrompent par .... La vue d’ensemble est dans Introduction et Lister les documents.
fields est un tableau JSON. expand aussi : l’exemple déplie priority en name, title et creation. Dans ce JSON, il manque une virgule après le name de la ligne. filters est une liste [champ, opérateur, valeur], combinés par AND. or_filters a la même syntaxe pour OR. La phrase publiée ne ferme pas l’accent grave après filters.
order_by vaut fieldname asc ou desc, espace encodé : title%20desc. limit_start et limit_page_length paginent. Depuis la v13, limit est l’alias de limit_page_length. as_dict=False renvoie des listes, pas des dictionnaires. debug=True met la requête et le temps dans exc. Le texte écrit « reqeusts ». L’exemple SQL lit tabToDo.name, tri modified DESC, limit 5 offset 10.
CRUD
En-têtes Accept et Content-Type en application/json. Le détail des écritures est aussi dans Manipuler les documents.
POST /api/resource/:doctype, corps JSON. Un ToDo « New ToDo » revient Open, priorité Medium, propriétaire Administrator, docstatus 0.
GET /api/resource/:doctype/:name. La description publiée est le texte Test description dans une balise de paragraphe. expand_links=True déplie les liens. L’exemple déplie priority.
PUT /api/resource/:doctype/:name n’envoie que les champs à changer. L’exemple ne change que description. DELETE renvoie {"message": "ok"}.
Méthodes et fichiers
Une méthode Python arbitraire doit être en liste blanche. GET /api/method/frappe.auth.get_logged_user renvoie le message [email protected]. GET si la méthode renvoie des valeurs. POST si elle change la base : après succès, frappe.db.commit() est appelé. Succès : clé message. Erreur : exc (pile) et exc_type. La valeur de retour est convertie en JSON.
POST /api/method/upload_file, Authorization: token xxxx:yyyy, champ formulaire file. Côté navigateur, FormData et XHR. Le code du bureau cité est FileUploader.vue, lignes 381 à 401 du commit indiqué.
Point d’attention
Le secret d’API ne s’affiche qu’à la génération. Vingt lignes et le seul name, tant qu’on ne passe ni fields ni limit. Un POST de méthode qui réussit est commité tout seul.