API core

Cette documentation explique comment interroger l’API REST d’ioi pour récupérer des données brutes depuis la base : lister des enregistrements d’un doctype, ou en lire un en détail.

Elle couvre uniquement la lecture de données. Elle s’appuie sur l’API REST native du framework Frappe, sur lequel ioi est construit.

Dans les exemples ci-dessous, remplacez <base-url> par l’URL de votre instance ioi.

---

Authentification #

L’accès à l’API se fait via une clé API (API Key) et un secret API (API Secret), générés depuis les paramètres de votre utilisateur.

Ces deux valeurs sont concaténées avec un : et envoyées dans l’en-tête HTTP Authorization, au format :

Authorization: token api_key:api_secret

Exemple - cURL #

curl http://<base-url>/api/method/frappe.auth.get_logged_user \
  -H "Authorization: token api_key:api_secret"

Exemple - JavaScript (fetch) #

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

Chaque appel décrit plus bas doit inclure cet en-tête Authorization.

---

Lister des documents #

Permet de récupérer une liste d’enregistrements d’un doctype donné.

GET /api/resource/:doctype

Par défaut, la réponse contient 20 enregistrements et n’affiche que le champ name.

Exemple de réponse :

{
  "data": [
    {"name": "f765eef382"},
    {"name": "2a26fa1c64"},
    {"name": "f32c68060f"}
  ]
}

Choisir les champs à retourner #

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

Exemple de réponse :

{
  "data": [
    {"description": "Business worker talk society...", "name": "f765eef382"},
    {"description": "This reveal as look near sister...", "name": "2a26fa1c64"}
  ]
}

Étendre un champ de type lien (expand) #

Récupère les détails complets d’un champ lié, plutôt que juste son identifiant.

GET /api/resource/:doctype?expand=["priority"]

Exemple de réponse : le champ priority retourne l’objet complet au lieu de son seul identifiant :

{
  "data": [
    {
      "name": "f765eef382",
      "priority": {
        "name": "a1b2c3",
        "title": "Medium",
        "creation": "2025-11-05 19:02:19.106966"
      }
    },
    {
      "name": "f765eef393",
      "priority": {
        "name": "a1b2c4",
        "title": "High",
        "creation": "2025-11-05 20:02:19.106966"
      }
    }
  ]
}

Filtrer les résultats #

Le paramètre filters prend un tableau de conditions au format ["champ", "opérateur", "valeur"], combinées en ET (AND) :

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

Pour combiner les conditions en OU (OR), on utilise or_filters avec la même syntaxe.

Trier les résultats #

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

Pagination #

GET /api/resource/:doctype?limit_start=5&limit_page_length=10

Exemple de réponse :

{
  "data": [
    {"name": "6234d15099"},
    {"name": "62f2181ee0"},
    {"name": "a50afbbfaa"},
    {"name": "aa12a5cf71"},
    {"name": "6ac9800d4e"},
    {"name": "4bcf8b701c"},
    {"name": "aee15f4c20"},
    {"name": "6ba753afef"}
  ]
}

Une syntaxe alternative existe avec limit :

GET /api/resource/:doctype?limit_start=5&limit=10

Format de réponse en liste #

Par défaut, chaque enregistrement est retourné sous forme de dictionnaire (clé/valeur). Pour obtenir une liste de valeurs plutôt qu’un dictionnaire :

GET /api/resource/:doctype?limit_start=5&limit=5&as_dict=False

Exemple de réponse : chaque enregistrement devient une liste de valeurs (ici, un seul champ retourné) plutôt qu’un dictionnaire :

{
  "data": [
    ["6234d15099"],
    ["62f2181ee0"],
    ["a50afbbfaa"]
  ]
}

Debug #

Pour afficher la requête SQL exécutée ainsi que son temps d’exécution :

GET /api/resource/:doctype?limit_start=10&limit=5&debug=True

Exemple de réponse : la requête SQL exécutée apparaît dans le champ exc, en plus des données :

{
  "data": [
    {"name": "4bcf8b701c"},
    {"name": "aee15f4c20"},
    {"name": "6ba753afef"},
    {"name": "f4b7e24abc"},
    {"name": "bd9156096c"}
  ],
  "exc": "[\"select `tabToDo`.`name`\\n\\t\\t\\tfrom `tabToDo`\\n\\t\\t\\t\\n\\t\\t\\t\\n\\t\\t\\t order by `tabToDo`.`modified` DESC\\n\\t\\t\\tlimit 5 offset 10\", \"Execution time: 0.0 sec\"]"
}

---

Lire un document précis #

Permet de récupérer le détail complet d’un enregistrement, à partir de son identifiant (name).

GET /api/resource/:doctype/:name

Exemple de 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>Test description</p>",
    "doctype": "ToDo"
  }
}

Étendre les champs liés #

Pour que les champs de type lien retournent l’objet complet plutôt que juste leur identifiant :

GET /api/resource/:doctype/:name?expand_links=True

Exemple de réponse : ici, priority retourne l’objet complet au lieu de son seul identifiant :

{
  "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": {
      "name": "a1b2c3",
      "title": "Medium",
      "creation": "2025-11-05 19:02:19.106966"
    },
    "description": "<p>Test description</p>",
    "doctype": "ToDo"
  }
}

---

Résumé #

Cette API permet exclusivement de consulter des données déjà présentes dans la base : listes d’enregistrements et documents individuels.