API Rest

Le modèle applicatif Dodock crée de nouveaux points de terminaison REST pour chaque type de document (DocType) créé dans le système. Vous pouvez aussi accèder aux méthodes python via leur chemin en pointillé en leur ajoutant un décorateur "whitelist".

Authentification

Vous pouvez vous authentifier grâce à une méthode basée sur des mots de passe ou grâce à une méthode basée sur des jetons d'accès.

Authentification par mot de passe

L'authentification par mot de passe utilise des cookies et les données de la session pour conserver l'authentification dans les requêtes subséquentes.
Dans la plupart des cas, la libraire que vous utilisez pour faire vos appels REST gère les données de la session, mais si ça n'est pas le cas utilisez plutôt la méthode par jetons.

fetch('http://<url-de-base>/api/method/login', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        usr: 'identifiant ou email',
        pwd: 'mot de passe'
    })
})
.then(r => r.json())
.then(r => {
    console.log(r);
})

Authentification par jeton

Un jeton est une paire de clé API et de secret d'API.
Vous devez d'abord créer un utilisateur pour l'API et générer des clés dans la section d'accès API du formulaire utilisateur.

Le jeton est généré en concaténant api_key et api_secret avec un double points :. Passez la chaîne de caractère du jeton api_key:api_secret dans l'en-tête d'autorisation de la requête.

fetch('http://<url-de-base>/api/method/frappe.auth.get_logged_user', {
    headers: {
        'Authorization': 'token api_key:api_secret'
    }
})
.then(r => r.json())
.then(r => {
    console.log(r);
})

Liste de documents

Pour obtenir une liste de documents pour un type de document (doctype) donné, envoyé une requête GET à /api/resource/:doctype.
Par défaut, cette requête vous renverra 20 documents et récupèrera uniquement le nom de ces documents.

GET /api/resource/:doctype

Réponse

{
  "data": [
    {
      "name": "b57566801d"
    },
    {
      "name": "b63b71df37"
    },
    {
      "name": "1fea4af0f4"
    },
    {
      "name": "4ca0cc6e0e"
    },
  ]
}

Vous pouvez indiquer quels champs récupérer dans le paramètre fields. Il faut que ce soit une liste JSON.

GET /api/resource/:doctype?fields=["field1", "field2"]

Vous pouvez filtrer les documents en passant un paramètre filters. Les filtres doivent être en liste, avec chaque filtre au format: champ, opérateur, valeur

GET /api/resource/:doctype?filters=[["field1", "=", "value1"], ["field2", ">", "value2"]]

Vous pouvez aussi passer un champ d'ordre et de tri. Il faut que le format soit nom_du_champ asc ou nom_du_champ desc. L'espace doit être encodé comme un URL.

GET /api/resource/:doctype?order_by=title%20desc

Vous pouvez aussi paginer les résultats en fournissant les paramètres limit_start et limit_page_length.

GET /api/resource/:doctype?limit_start=10&limit_page_length=20
```New

# Body
{"description": "Nouvelle ToDo"}

Réponse

{
  "data": {
    "name": "af2e2d0e33",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:19:00.281026",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "Nouvelle ToDo",
    "doctype": "ToDo"
  }
}

LECTURE

Récupérez un document en envoyant une requête GET à /api/resource/:doctype/:name.

GET /api/resource/:doctype/:name

Réponse

{
  "data": {
    "name": "bf2e760e13",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:19:00.281026",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "<p>Description Test</p>",
    "doctype": "ToDo"
  }
}

MISE A JOUR

Mettez à jour un document en envoyant une requête PUT à /api/resource/:doctype/:name. Vous n'avez pas besoin d'envoyer le document entier, seulement les champs que vous souhaitez mettre à jour.

PUT /api/resource/:doctype/:name

# Body
{"description": "Nouvelle description"}

Réponse

{
  "data": {
    "name": "bf2e760e13",
    "owner": "Administrator",
    "creation": "2019-06-03 14:19:00.281026",
    "modified": "2019-06-03 14:21:00.785117",
    "modified_by": "Administrator",
    "idx": 0,
    "docstatus": 0,
    "status": "Open",
    "priority": "Medium",
    "description": "New description",
    "doctype": "ToDo"
  }
}

SUPPRESSION

Supprimez une document en envoyant une requête DELETE à /api/resource/:doctype/:name.

DELETE /api/resource/:doctype/:name

Réponse

{"message": "ok"}

Appels de procédures à distance

Dodock vous permet de lancer des méthodes python arbitraires en utilisant l'API REST pour gérer des logiques personnalisées. Ces méthodes doivent être décorées avec la méthode frappe.whitelist() pour les rendre accessible via REST.

Pour lancer la méthode python whitelisté frappe.auth.get_logged_user, envoyez une requête au point de terminaison /api/method/frappe.auth.get_logged_user.

GET /api/method/frappe.auth.get_logged_user

Réponse

{
  "message": "john@doe.com"
}

• Si votre méthode renvoie uniquement des valeurs, vous devez envoyer une requête GET.
• Si votre méthode modifie l'état de la base de données, utilisez POST. Après une requête POST réussie, le framework appelle automatiquement frappe.db.commit() pour valider les modifications dans la base de données.
• Une réponse de réussite renverra un objet JSON avec une clé message.
• Une réponse d'erreur renverra un objet JSON avec une clé exc contenant une trace d'erreur et exc_type contenant l'exception générée.
• La valeur de sortie de la méthode sera convertie en JSON et envoyée comme réponse.

Téléchargement de fichiers

Il existe une méthode dédiée /api/method/upload_file qui accepte un fichier binaire et le télécharge dans le système.

Voici la commande curl:

curl -X POST \
  http://<url-de-base>/api/method/upload_file \
  -H 'Accept: application/json' \
  -H 'Authorization: token xxxx:yyyy' \
  -F file=@/chemin/vers/le/fichier.png

Si vous utilisez du code client en Javascript pour télécharger vos fichiers, vous pouvez ajouter les fichiers téléchargés à un objet FormData et envoyer une requête XHR.