API de découverte des méthodes (API v2)

L'API v2 expose une API de découverte sous /api/v2/discovery. Un client authentifié l'utilise pour lister les méthodes qu'il peut appeler et pour lire la signature d'une méthode avant de l'appeler.

Autorisations

Chaque route appelle frappe.only_for("Desk User").

• Un utilisateur qui a accès au bureau (rôle « Utilisateur du bureau ») peut interroger l'API.
• Un utilisateur du site web, sans accès au bureau, reçoit une erreur 403.
• Une méthode de Server Script (type API) apparaît uniquement si l'utilisateur peut lire ce Server Script. Les autorisations utilisateur sur le type de document Server Script s'appliquent aussi.

L'authentification est la même que pour le reste de l'API : session, jeton (Authorization: token <clé>:<secret>) ou OAuth. Voir API REST v1.

Routes

Toutes les routes acceptent uniquement GET.

Comme les autres routes v2, la réponse est placée dans la clé data.

Index racine

/api/v2/discovery renvoie le type discovery, le nombre de méthodes (resources.methods, resources.doctype_methods) et la liste des routes (links).

Recherche

/api/v2/discovery/search découpe le paramètre q en mots. Un résultat correspond quand tous les mots sont dans son chemin, son type de document, son nom, sa description ou sa docstring. La casse n'a pas d'importance. Sans q, la route renvoie les 50 premières entrées de l'index.

Index des méthodes

/api/v2/discovery/method renvoie un objet {"type": "method_index", "methods": [...]}. Chaque entrée a une clé kind :

• rpc : une fonction Python décorée par @frappe.whitelist() au niveau d'un module, ou un Server Script de type API. L'entrée contient path et, si la fonction a une docstring, description (sa première ligne).
• doctype : une méthode whitelistée d'un contrôleur de document. L'entrée contient doctype, method et description.

L'index des méthodes de contrôleur exclut les méthodes standard de la classe Document et les types de documents enfants (tables).

Détail d'une méthode

/api/v2/discovery/method/<méthode> renvoie, pour une fonction whitelistée :

La route applique les surcharges déclarées dans le hook override_whitelisted_methods. Une méthode inconnue ou non whitelistée renvoie une erreur « n'existe pas ».

Pour un Server Script de type API, la réponse contient name (le nom du Server Script), http_methods (GET, POST, PUT, DELETE), une liste params vide et l'endpoint.

Détail d'une méthode de contrôleur

/api/v2/discovery/doctype/<doctype>/method/<méthode> renvoie :

Les méthodes submit, cancel et discard n'apparaissent que si le type de document est validable. La méthode rename n'apparaît que si le type de document autorise le renommage. Un type de document enfant renvoie une erreur « n'existe pas ».

Exemple

Cet exemple cherche la méthode qui compte des documents, puis lit sa signature. Remplacez l'URL du site et le jeton par les vôtres.

curl -s "https://votre-site.dokos.cloud/api/v2/discovery/search?q=get_count" \
     -H "Authorization: token VOTRE_CLE_API:VOTRE_SECRET_API"

curl -s "https://votre-site.dokos.cloud/api/v2/discovery/method/frappe.client.get_count" \
     -H "Authorization: token VOTRE_CLE_API:VOTRE_SECRET_API"

La deuxième requête renvoie une réponse de cette forme (le champ source est tronqué) :

{
  "data": {
    "type": "method",
    "kind": "rpc",
    "path": "frappe.client.get_count",
    "name": "get_count",
    "http_methods": ["GET", "POST", "PUT", "DELETE", "QUERY"],
    "allow_guest": false,
    "params": [
      {"name": "doctype", "required": true, "type": "str"},
      {"name": "filters", "required": false, "type": "str | list | dict[str, typing.Any] | None"},
      {"name": "debug", "required": false, "default": false, "type": "int | bool"},
      {"name": "cache", "required": false, "default": false, "type": "int | bool"}
    ],
    "endpoint": "/api/v2/method/frappe.client.get_count",
    "source": "@frappe.whitelist()\ndef get_count(..."
  }
}

Le client appelle ensuite l'endpoint indiqué, par exemple GET /api/v2/method/frappe.client.get_count?doctype=Customer. Voir API REST v2.

Cache

L'index des méthodes est construit à partir du code des applications installées, puis gardé en cache.

• Le cache est reconstruit en tâche de fond après chaque bench migrate, dans la file default.
• Il expire après 24 heures, ou après une heure quand le mode développeur est actif.
• Si le cache est vide, l'API lance sa construction et renvoie une erreur 503 : « API discovery cache is being generated. Please try again in 10 seconds. ». Refaites la requête quelques secondes plus tard.

Exposer le code source des méthodes

La clé source contient le code Python de la méthode uniquement si l'application qui la définit l'autorise. Elle déclare pour cela le hook expose_discovery_source dans son hooks.py :

# hooks.py de votre application
expose_discovery_source = True

Dodock (frappe) et Dokos (erpnext) déclarent ce hook, car ce sont des applications open source. Pour les autres applications, la clé source est absente de la réponse, sauf si elles déclarent le hook. N'activez pas ce hook dans une application dont le code ne doit pas être diffusé.

Le hook ajoute uniquement des métadonnées à la réponse. Il ne change ni l'exécution des méthodes, ni les autorisations.

Limites

• L'API ne produit pas de spécification OpenAPI. Pour les types de documents de Dokos, voir la Référence OpenAPI de Dokos.
• Une fonction apparaît dans l'index uniquement si elle est décorée par @frappe.whitelist() au niveau du module. Une fonction whitelistée autrement (par exemple, attribuée dynamiquement) n'apparaît pas.
• Les webhooks ne font pas partie de l'index.

Voir aussi

• API REST v2
• Serveur MCP
• Référence développeur