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".
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.
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);
})
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);
})
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"
}
}
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"
}
}
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"
}
}
Supprimez une document en envoyant une requête DELETE à /api/resource/:doctype/:name.
DELETE /api/resource/:doctype/:name
Réponse
{"message": "ok"}
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"
}
GET.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.message.exc contenant une trace d'erreur et exc_type contenant l'exception générée.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.