Le constructeur d'APIs

Chaque API de Keplin est une opération GraphQL de l'app : une query qui lit des données ou une mutation qui en écrit. Les écrans de l'app elle-même, les rapports, les workflows et les systèmes externes appellent tous les mêmes APIs — ce que vous définissez ici est l'unique chemin d'entrée et de sortie des données de l'application.

Une API peut avoir l'une de deux natures :

Nature	Ce que c'est	Où cela s'approfondit
Pipeline	Une séquence d'étapes (Requête SQL, Appel HTTP, Script) qui s'exécutent dans l'ordre ; le résultat de la dernière est la réponse.	Cette page
Table	Un bloc unique relié à une table du modèle de données, qui génère pour vous les opérations de lecture et d'écriture (get/add/update/delete).	L'API GraphQL du modèle

Cette page couvre le constructeur lui-même : créer l'API, définir des arguments, monter le pipeline, tester sans enregistrer et publier.

#Où vivent les APIs

À l'intérieur d'une app, ouvrez le panneau Code dans la sidebar. La section APIs liste les APIs existantes — vous pouvez les organiser en dossiers avec Nouveau dossier — et chacune s'ouvre comme un onglet de l'espace de travail. L'app a aussi une page de résumé avec la liste complète, le type et l'état de chaque API, et l'adresse à laquelle elles sont servies.

#Créer une API

1. Dans le panneau Code, sur la ligne APIs, cliquez sur le bouton + (Nouvelle API). Le bouton Nouvelle API de la page de résumé vous mène au même endroit : l'espace de travail de l'app.
2. Donnez un Nom. Le nom est le champ GraphQL que les clients vont appeler, donc suivez la règle : lettres, chiffres et underscore, sans commencer par un chiffre — par exemple getOportunidadesPorConta.
3. Cliquez sur Créer une API. L'API naît en brouillon et le constructeur s'ouvre à la suite — c'est là que vous décidez de la nature (blocs SQL, HTTP, script ou table).

#Le constructeur en un coup d'œil

L'en-tête du constructeur affiche le nom, un badge avec le type (query, mutation ou table) et l'état (publiée ou brouillon). À droite se trouvent les commandes qui valent pour l'API entière :

Commande	Ce qu'elle fait
Publiée	Active/désactive la publication. Une API en brouillon n'est visible que pour qui la construit ; les clients externes ne la voient pas.
Publique (sans session)	Rend l'API accessible sans session ni clé API — pour les écrans publics de l'app. Voir APIs publiques.
Enregistrer	Enregistre l'API telle quelle. Enregistrer est toujours possible avec un nom et des arguments valides — un travail à moitié fait s'enregistre quand même.

En dessous, le travail se divise en trois onglets :

Onglet	Pour quoi
Construire	Identification, arguments et le pipeline d'étapes.
Tester	Exécuter le pipeline en brouillon et essayer l'API comme un client.
Docs	Des exemples prêts à copier pour appeler l'API de l'extérieur.

#Identification

Dans la section Identification, vous définissez :

• Opération — Query — lit des données ou Mutation — écrit des données. Le choix est sémantique et pratique : les mutations demandent confirmation avant chaque exécution de test, parce qu'elles écrivent pour de vrai.
• Nom — le champ GraphQL. Si le nom n'est pas valide, le constructeur avertit : « camelCase simple : lettres, chiffres et underscore, sans commencer par un chiffre. »

Dans une API de Table, il n'y a pas de choix d'opération — les opérations découlent des actions CRUD que vous activez dans le bloc Table.

#Arguments

La section Arguments déclare les paramètres que les clients passent à l'API. Chaque argument a :

Colonne	Ce que c'est
Nom	Identifiant de l'argument (lettres, chiffres, underscore ; ne commence pas par un chiffre).
Type	L'un de : String, Int, Float, Boolean, ID, JSON, Upload.
Oblig.	Si le client est obligé d'envoyer l'argument.
Par défaut	Valeur utilisée quand le client n'envoie rien.
Valeur de test	Uniquement pour le bouton Exécuter de l'onglet Tester — cela n'affecte pas les clients.

À l'intérieur du pipeline, les arguments sont disponibles comme :nom dans les étapes SQL et HTTP, et comme input["args"]["nom"] dans l'étape Script.

#Des fichiers comme argument (type Upload)

Un argument de type Upload reçoit un fichier. Dans ce cas, la colonne Par défaut laisse place au choix du stockage : De l'app utilise le stockage par défaut ; en alternative, choisissez l'un des stockages configurés dans les paramètres de l'app (section Stockage). Ainsi, une API qui reçoit des factures et une autre qui reçoit des photographies n'ont pas à conserver les fichiers au même endroit.

Ce qui se passe quand l'API est appelée avec un fichier :

1. Le fichier est conservé dans le stockage choisi.
2. Dans le pipeline, l'argument cesse d'être le fichier brut et devient une référence avec filename, mimeType, size et un token — c'est cela qu'une étape Script reçoit dans input["args"]["nomDeLArg"].
3. L'app garde l'enregistrement du fichier, comme n'importe quel autre fichier envoyé par les utilisateurs.

Pour tester, la colonne de valeur de test se transforme en sélecteur de fichier — choisissez-en un sur votre ordinateur et cliquez sur Exécuter.

De l'extérieur, le fichier s'envoie comme variable multipart de la requête GraphQL (le format standard d'upload GraphQL) ; à l'intérieur de la plateforme, les écrans s'en occupent pour vous.

#Le pipeline

La section Pipeline est là où l'API prend corps. Les règles sont simples :

• Les étapes s'exécutent dans l'ordre ; le résultat de la dernière est la réponse de l'API.
• Chaque étape (à partir de la deuxième) peut recevoir le résultat de la précédente — le badge « reçoit le résultat de l'étape N » le rappelle.
• Dans les étapes SQL et HTTP, le résultat précédent est dans :prev, et il accepte des chemins : :prev.id, :prev.0.id.
• Vous ajoutez des étapes avec les boutons Requête SQL, Appel HTTP et Script ; le bouton Table convertit l'API en nature de table (et ne se combine pas avec les autres blocs).

Tant qu'il n'y a pas de blocs, la section suggère le chemin : le défaut est une Table du modèle ; en alternative, on construit un pipeline avec les étapes décrites ci-dessous.

#Étape Requête SQL

1. Choisissez le Datasource — l'une des bases de données enregistrées dans l'app. Sans datasources, l'étape affiche le raccourci pour créer le premier.
2. Écrivez la requête dans l'éditeur. Écrivez : pour autocompléter les arguments ; l'éditeur connaît les tables et les colonnes du datasource choisi et les suggère pendant que vous écrivez.
3. Si la requête renvoie par nature une seule ligne (un total, un enregistrement par clé), activez Renvoyer seulement la première ligne — la réponse passe de liste à objet.

Les valeurs de :argument et de :prev partent toujours paramétrées vers la base de données — jamais concaténées dans le texte de la requête. Cela vous protège de l'injection SQL sans aucun effort.

#Étape Appel HTTP

Pour parler avec des services externes :

1. Choisissez la Méthode (GET, POST, PUT, PATCH ou DELETE) et remplissez l'URL — ex. : https://api.exemple.fr/clients/:clientId.
2. Ajoutez des Headers avec Ajouter un header — par exemple Authorization avec la valeur Bearer :token.
3. Sur les méthodes avec un corps, remplissez le Body ; activez Envoyer en JSON pour que le corps parte avec le bon type de contenu.

:nomDeLArg et :prev sont remplacés dans l'URL, les headers et le body.

#Étape Script

L'étape Script exécute un script de l'app — la même logique que vous pouvez lancer à la main ou par planification, désormais comme partie d'une API :

1. Choisissez le Script dans la liste (la liste montre le nom et le langage de chacun ; seuls les scripts actifs apparaissent). Sans scripts, l'étape affiche le raccourci pour créer le premier.
2. Décidez si l'étape Reçoit le résultat de l'étape précédente — sur la première étape du pipeline, cet interrupteur ne s'applique pas.

Le contrat avec le script est clair : les arguments de l'API arrivent dans input["args"], le résultat de l'étape précédente dans input["prev"], et la valeur renvoyée par la fonction main(input) passe à l'étape suivante (ou est la réponse, si c'est la dernière étape).

#Réordonner et retirer des étapes

Chaque carte d'étape a des flèches pour Déplacer vers le haut / Déplacer vers le bas et une corbeille pour Retirer l'étape. Changer le pipeline invalide le résultat du dernier test — relancez Exécuter pour voir des résultats frais.

#Tester sans enregistrer

L'onglet Tester a deux outils. Le premier, Tester le pipeline (brouillon), exécute le pipeline TEL QUEL dans le constructeur, sans enregistrer :

1. Remplissez les valeurs de test des arguments (dans la section Arguments).
2. Cliquez sur Exécuter. Sur une mutation, le constructeur demande confirmation — « Exécuter la mutation maintenant ? » — parce que le test s'exécute pour de vrai sur les datasources et qu'une mutation effectue de vraies écritures.
3. Lisez le résultat : le badge Succès/Erreur avec la durée, la Réponse complète (les réponses très grandes apparaissent tronquées), et avec plus d'une étape, le Résultat par étape — chaque étape avec un badge ok/erreur, pour voir exactement où le pipeline a cassé.
4. Si les étapes ont écrit des logs (un script qui imprime, par exemple), ils apparaissent dans le bloc Logs.

#Le return type

Le return type est la forme de la réponse dans le schéma GraphQL — c'est lui qui dit aux clients quels champs ils peuvent sélectionner. Le constructeur l'infère du résultat réel : après chaque exécution, regardez le bloc Return type (inféré). S'il diffère de ce qui est enregistré, l'avertissement « Ce return type n'est pas encore enregistré » apparaît avec le bouton Enregistrer le return type — et un point ambre sur le bouton Enregistrer vous le rappelle aussi.

#Essayer comme un client

Le second outil de l'onglet Tester est un environnement GraphQL interactif pointé sur l'endpoint de l'app — vous écrivez des opérations, vous avez l'autocomplétion du schéma et vous voyez les réponses. Comme vous êtes authentifié, les brouillons apparaissent aussi. Le bouton Ouvrir dans une fenêtre ouvre le même environnement dans un onglet du navigateur. Les détails sont dans le chapitre suivant, dans L'API GraphQL du modèle.

#Publier

L'interrupteur Publiée contrôle qui voit l'API :

• Brouillon — seul celui qui construit la voit (dans les sessions authentifiées, les opérations apparaissent marquées comme brouillon). Les clients externes et les utilisateurs de l'app ne la voient pas, pas même par listage du schéma.
• Publiée — elle entre dans le schéma pour tous les clients qui y ont accès.

Pour enregistrer comme publiée, l'API doit être complète. Le constructeur affiche les blocages à côté de l'en-tête — par exemple « Étape 2 : le SQL est vide. » ou, dans une API de table, « Pour enregistrer comme publiée, choisissez la table et au moins une action CRUD. » Ces avertissements n'empêchent jamais l'Enregistrer en brouillon : ils n'empêchent que la publication.

#La documentation générée (onglet Docs)

L'onglet Docs répond à la question « comment j'appelle cela de l'extérieur ? ». Il est généré à partir de la version enregistrée — enregistrez d'abord l'API — et affiche :

• L'endpoint (POST /api/graphql/gestao-clientes), avec un bouton pour copier.
• La note d'authentification : le header x-api-key est obligatoire pour les clients externes — les clés se génèrent dans Clés API. Dans l'onglet Tester (session interne), ce n'est pas nécessaire.
• Une entrée par opération de l'API avec quatre blocs prêts à copier : Requête GraphQL, Variables, curl et JavaScript (fetch). Dans une API de table, toutes les opérations actives apparaissent (get, count, add, update, delete).

#Pourquoi ne… ?

• Pourquoi n'arrivé-je pas à publier ? Il manque que le pipeline soit complet — lisez les blocages à côté de l'en-tête : chaque étape manquante est listée avec son numéro et le motif.
• Pourquoi l'Exécuter me demande-t-il confirmation ? L'API est une mutation : le test effectue de vraies écritures. Vérifiez que vous pointez sur des données de test.
• Pourquoi je ne vois pas ma nouvelle API dans l'environnement de test GraphQL ? Enregistrez d'abord — l'environnement répond au sujet de la version enregistrée. Les brouillons enregistrés apparaissent (vous êtes authentifié) ; pour les clients externes, seulement une fois publiés.
• Pourquoi ne puis-je pas ajouter une étape SQL à une API de Table ? Une API Table ne se combine pas avec d'autres blocs — retirez d'abord le bloc Table (ou les étapes, dans le sens inverse).