Découvrir les méthodes de l'API

Dokos expose une API REST qui permet d'interagir avec les documents et les fonctionnalités du système. Pour faciliter l'intégration et le développement, Dokos propose des endpoints de découverte qui listent les méthodes disponibles, y compris celles définies dans les contrôleurs de documents.

Endpoints de découverte

1. Découverte des méthodes standard

Endpoint : /api/method/discovery

Cet endpoint retourne la liste des méthodes standard disponibles dans l'API, organisées par module et doctype.

Exemple de requête :

curl -X GET "https://votre-instance.dokos.cloud/api/method/discovery" \
-H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET"

Exemple de réponse :

{
  "docs": {
    "ToDo": {
      "methods": [
        {
          "name": "frappe.desk.doctype.todo.todo.create_todo",
          "docstring": "Crée une nouvelle tâche ToDo.",
          "parameters": [
            {
              "name": "description",
              "type": "str",
              "required": true
            }
          ]
        }
      ]
    }
  },
  "standard": {
    "frappe": {
      "core": [
        {
          "name": "frappe.core.doctype.user.user.get_users",
          "docstring": "Récupère la liste des utilisateurs."
        }
      ]
    }
  }
}

2. Découverte des méthodes des contrôleurs de documents

Endpoint : /api/method/discovery/docs

Cet endpoint retourne la liste des méthodes définies dans les contrôleurs de documents (fichiers Python associés à un doctype). Ces méthodes sont souvent utilisées pour étendre les fonctionnalités des documents.

Exemple de requête :

curl -X GET "https://votre-instance.dokos.cloud/api/method/discovery/docs" \
-H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET"

Exemple de réponse :

{
  "ToDo": {
    "methods": [
      {
        "name": "send_reminder",
        "docstring": "Envoie un rappel pour une tâche ToDo.",
        "parameters": [
          {
            "name": "days_before_due",
            "type": "int",
            "default": 1
          }
        ]
      }
    ]
  }
}

Utilisation des méthodes découvertes

1. Appeler une méthode standard

Pour appeler une méthode standard, utilisez l'endpoint /api/method suivi du nom complet de la méthode.

Exemple :

curl -X POST "https://votre-instance.dokos.cloud/api/method/frappe.desk.doctype.todo.todo.create_todo" \
-H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{"description": "Tester la découverte des méthodes API"}'

2. Appeler une méthode de contrôleur de document

Pour appeler une méthode définie dans un contrôleur de document, utilisez l'endpoint /api/resource/{doctype}/{docname}/method/{method_name}.

Exemple :

curl -X POST "https://votre-instance.dokos.cloud/api/resource/ToDo/TODO-001/method/send_reminder" \
-H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{"days_before_due": 2}'

Bonnes pratiques

1. Authentification : Les endpoints de découverte nécessitent une authentification avec un token API valide. Assurez-vous que l'utilisateur associé au token dispose des permissions nécessaires (généralement System Manager).
2. Cache : Les résultats des endpoints de découverte sont mis en cache pour améliorer les performances. Si vous ajoutez ou modifiez une méthode, vous pouvez forcer le rafraîchissement du cache en appelant l'endpoint /api/method/frappe.api.discovery.clear_cache.
3. Documentation des méthodes : Pour que vos méthodes apparaissent correctement dans les résultats de découverte, assurez-vous de les documenter avec des docstrings claires et complètes dans le code.

Exemple complet : Intégration avec un script Python

Voici un exemple de script Python qui utilise les endpoints de découverte pour explorer les méthodes disponibles et appeler une méthode de contrôleur :

import requests
import json

# Configuration
base_url = "https://votre-instance.dokos.cloud"
api_key = "YOUR_API_KEY"
api_secret = "YOUR_API_SECRET"

# Récupérer les méthodes des contrôleurs de documents
response = requests.get(
    f"{base_url}/api/method/discovery/docs",
    headers={
        "Authorization": f"token {api_key}:{api_secret}"
    }
)

data = response.json()
print("Méthodes disponibles pour le doctype ToDo:")
for method in data.get("ToDo", {}).get("methods", []):
    print(f"- {method['name']}: {method['docstring']}")

# Appeler une méthode de contrôleur
if data.get("ToDo", {}).get("methods"):
    method_name = data["ToDo"]["methods"][0]["name"]
    todo_name = "TODO-001"  # Remplacez par un nom de tâche existant
    
    response = requests.post(
        f"{base_url}/api/resource/ToDo/{todo_name}/method/{method_name}",
        headers={
            "Authorization": f"token {api_key}:{api_secret}",
            "Content-Type": "application/json"
        },
        data=json.dumps({"days_before_due": 2})
    )
    
    print(f"Résultat de l'appel à {method_name}:", response.json())

Diagramme de flux

Voici un diagramme qui illustre le processus de découverte et d'appel des méthodes API :

      
sequenceDiagram
    participant Développeur
    participant Client
    participant Dokos

    

Résolution des problèmes

Problème : Les méthodes ne apparaissent pas dans la découverte

1. Vérifiez les permissions : Assurez-vous que l'utilisateur associé au token API a le rôle System Manager.
2. Vérifiez la documentation : Les méthodes doivent avoir une docstring pour apparaître dans les résultats.
3. Rafraîchissez le cache : Appelez /api/method/frappe.api.discovery.clear_cache pour forcer le rafraîchissement.

Problème : Erreur lors de l'appel d'une méthode

1. Vérifiez les paramètres : Assurez-vous que tous les paramètres requis sont fournis.
2. Vérifiez les permissions : L'utilisateur doit avoir les permissions nécessaires sur le document.
3. Vérifiez le nom de la méthode : Assurez-vous que le nom de la méthode est correct et qu'elle est bien définie dans le contrôleur.

Conclusion

Les endpoints de découverte des méthodes API de Dokos offrent une manière puissante d'explorer et d'utiliser les fonctionnalités disponibles, y compris celles définies dans les contrôleurs de documents. Cela facilite l'intégration avec d'autres systèmes et le développement d'applications personnalisées.

Pour aller plus loin, consultez la documentation officielle de l'API de Frappe pour plus de détails sur les méthodes standard et les bonnes pratiques de développement.