Points d'accès d'API
Un point d'accès (endpoint) est un appel nommé d'un connecteur d'API : soumettre cet état, lire ces clients, créer une commande. Une fois déclaré, il s'utilise partout sans une ligne de code — comme source d'un écran, dans une action d'écran, un service, une étape de tâche, un test, par l'assistant IA ou par un appelant extérieur — et chaque point d'accès a sa propre permission.
Accès : Liberty Next → Données → Connecteurs, un connecteur d'API, onglet Points d'accès.
Vue d'ensemble
La liste
Les points d'accès sont classés par ordre alphabétique, avec une zone de recherche au-delà de cinq (nom, libellé, chemin, méthode, description, groupe). Ceux qui partagent un groupe se rangent sous son titre, qui se replie et affiche leur nombre.
Chaque carte commence par une pastille — la méthode HTTP, FN pour un point d'accès servi par une fonction, ACT pour un point d'accès servi par un service — suivie du nom, du libellé et, le cas échéant, de la mention modifie des données.
| Bouton | Action |
|---|---|
| Ajouter un point d'accès | Demande un nom et ouvre un point d'accès vierge. |
| Créer à partir de… | Écrit un point d'accès d'après ce que le serveur décrit — voir plus bas. Affiché quand le connecteur a des générateurs. |
| Vérifier N générés | Réinterroge le serveur pour chaque point d'accès généré et liste ceux qui ne correspondent plus. |
L'onglet Test exécute n'importe quel point d'accès sur le connecteur tel qu'il est à l'écran, sans enregistrer : ses paramètres sous forme de champs, puis le résultat.
Les quatre étapes
Un point d'accès est dessiné en quatre cartes — Ce qu'il est → Entrées → L'appel → La réponse —, chacune résumant son contenu ; les champs de l'étape choisie s'affichent à côté.
Ce qu'il est
| Champ | Signification |
|---|---|
| Nom, Libellé, Description | L'identifiant utilisé par les actions et les permissions, le libellé court des listes, une phrase de description. |
| Modifie des données | À cocher quand l'appel soumet, crée ou lance quelque chose — voir Les points d'accès qui modifient des données. |
| Groupe | Le titre sous lequel le point d'accès est rangé. Affichage seulement. |
| Créé à partir de | Pour un point d'accès généré, son origine, avec Actualiser depuis le serveur. |
Entrées
Chaque paramètre est une ligne — son nom, son libellé, sa valeur par défaut, Obligatoire — qui s'ouvre pour être modifiée.
| Champ | Signification |
|---|---|
| Nom, Libellé | Le {{NOM}} employé dans le chemin, les en-têtes ou le corps, et le libellé de son champ. |
| Valeur par défaut | Reprise quand l'appelant omet le paramètre ou le laisse vide. |
| Exemple, Aide — quoi y mettre | Affichés sous le champ partout où le point d'accès se renseigne, et transmis à l'assistant IA. |
| Valeurs autorisées | Une liste fermée : le champ devient une liste déroulante, toute autre valeur est refusée avant tout envoi, et la casse est corrigée. |
| Obligatoire | Un appel sans ce paramètre est refusé avant tout envoi. |
L'appel
Méthode et Chemin de l'URL, En-têtes supplémentaires, Content-Type, Corps (avec Formater le JSON) et Paramètres de requête. Ne pas envoyer un paramètre de requête dont la valeur est vide n'envoie que les paramètres renseignés, pour un serveur qui lit un paramètre vide comme un filtre sur rien.
À la place d'un appel HTTP, le point d'accès peut être Servi par une fonction ou Servi par une action — voir plus bas.
La réponse
| Champ | Signification |
|---|---|
| Lignes | L'emplacement de la liste d'enregistrements dans la réponse. Un écran peut alors lire le point d'accès comme il lit une requête. |
| Colonnes | Nom de colonne = clé d'un enregistrement (AN8=z_AN8_19) : les colonnes, dans l'ordre, nommées pour que le dictionnaire les reconnaisse. |
| Titres des colonnes | L'endroit où la réponse donne son titre à chaque clé — le libellé d'une colonne que ni l'écran ni le dictionnaire ne nomment. |
| Paramètre du nombre de lignes | Le paramètre qui porte le nombre maximal de lignes : un écran le renseigne avec son propre Max lignes. |
| Indicateur « autres lignes » | L'endroit où le serveur signale qu'il y a plus que ce qu'il a retourné : l'écran indique alors un résultat tronqué. |
| Champs d'erreur | L'endroit où le serveur place ses erreurs quand il répond 200 malgré tout : un contenu à cet endroit fait de l'appel un échec, avec ce contenu comme erreur. |
| Champs d'avertissement | L'endroit où le serveur place ses avertissements : signalés avec la réponse, l'appel reste valide. |
| Champ de réponse, Correspondances de réponse | La partie de la réponse retournée, et des noms logiques associés à des chemins de la réponse. |
Un chemin peut se terminer par un filtre sur les éléments d'une liste — result.errors[errorLevel=1] — pour un serveur qui range ses erreurs et ses avertissements dans la même liste.
Créer à partir de…
Un point d'accès générique — lancer n'importe quel état, avec du JSON pour tout ce qui dépend de l'état — est difficile à renseigner. Quand l'application placée derrière le connecteur fournit des générateurs, Créer à partir de… écrit à la place un point d'accès dédié :
- Rechercher l'objet sur le serveur.
- Répondre à quelques questions — quelles colonnes, quelles options.
- Créer le point d'accès : un paramètre nommé par entrée, avec son libellé, son aide et sa valeur par défaut. Il est ajouté sans être enregistré, et ouvert pour relecture.
Un générateur peut aussi construire plusieurs points d'accès à la fois, ou un écran complet : la fenêtre demande alors l'application, l'identifiant de l'écran, son titre et s'il faut l'ajouter au menu, puis crée les points d'accès et l'écran en une seule passe validée — rien n'est écrit si un élément est invalide. Un point d'accès déjà présent est conservé tel quel et utilisé par le nouvel écran, sauf si Remplacer les N point(s) d'accès qui existent déjà est coché.
Un point d'accès généré garde la trace de son origine. Actualiser depuis le serveur le reconstruit et montre ce qui change avant de l'appliquer : l'adresse, le corps et les paramètres suivent le serveur ; le nom, le libellé, la description et ce qui a été écrit sur un paramètre conservé sont gardés.
Les générateurs du connecteur AIS de JD Edwards sont décrits dans Nomajde — Créer à partir de….
Les points d'accès qui modifient des données
Un point d'accès marqué Modifie des données est traité à part :
- un écran peut le désigner comme insertion, mise à jour ou suppression — voir Un écran sur un point d'accès d'API ;
- l'assistant IA ne l'appelle pas comme une lecture : il faut que l'Outil API et les Outils d'écriture soient activés dans Administrer → App → Assistant IA, que l'utilisateur soit autorisé à modifier des données par l'assistant, et l'assistant propose une carte dans la conversation — rien n'est envoyé tant que l'utilisateur ne l'applique pas. En MCP, Autoriser les modifications en MCP est également nécessaire ;
- l'appel est consigné dans l'utilisation de l'IA, comme les autres modifications faites par l'assistant.
Un point d'accès non marqué est traité comme une lecture : marquer tous les points d'accès qui écrivent.
Servi par une fonction
Un seul appel HTTP ne peut pas tout faire : modifier un enregistrement qu'un serveur ne propose que par un formulaire suppose de le retrouver, de vérifier qu'un seul a été trouvé, puis d'agir. Servi par une fonction désigne une fonction du plugin d'une application qui répond à la place de l'appel HTTP. Ses arguments sont les paramètres du point d'accès ; sa réponse est traitée comme une réponse — lignes, champs d'erreur et d'avertissement, correspondances, Modifie des données. Pour un écran, une action, une tâche ou l'assistant, c'est un point d'accès comme un autre.
Servi par un service
Servi par une action désigne un service : ses étapes — requêtes, autres points d'accès, fonctions, conditions, boucles — s'exécutent sur le serveur et répondent comme un seul point d'accès. Les paramètres du point d'accès sont les entrées du service ; ce que le service retourne est la réponse. Il s'exécute avec la permission du point d'accès : qui peut appeler le point d'accès exécute ses étapes. Exposer, dans la page Services, crée un tel point d'accès en un clic.
Permissions et sûreté
Chaque point d'accès a sa permission, api:<connecteur>:<point d'accès> : un rôle peut être autorisé pour un état ou une orchestration, sans l'être pour tous. Cette permission tient parce qu'une valeur ne peut jamais détourner un appel :
- dans le chemin, une valeur ne peut ni remonter hors du chemin du point d'accès, ni donner une autre adresse ;
- dans un corps JSON, une valeur placée dans une chaîne reste dans cette chaîne ;
- dans un corps de formulaire, une valeur ne peut pas ajouter une paire ;
- un fichier envoyé par un appel fait pour le compte d'un utilisateur reste dans le dossier désigné par le point d'accès.
Un appel qui enfreindrait l'une de ces règles est refusé avant tout envoi.
Ce que voit l'appelant en cas d'échec
- Un serveur injoignable est désigné par son adresse : cannot connect to https://host:8999 — check the connector's base URL.
- Une erreur HTTP reprend les termes du serveur quand les champs d'erreur les trouvent.
- Une liste absente de l'endroit indiqué par le point d'accès est une erreur qui nomme ce que contient la réponse, et non un écran vide.
Conseils & bonnes pratiques
- Rédiger l'aide et l'exemple de chaque paramètre : ils servent autant aux personnes qui remplissent le formulaire qu'à l'assistant.
- Préférer plusieurs points d'accès précis à un point d'accès générique en JSON : chacun a sa permission et son formulaire.
- Déclarer les champs d'erreur de tout serveur qui répond 200 avec ses erreurs dans le corps ; sinon, un enregistrement refusé passe pour un succès.
- Regrouper sous un même titre les points d'accès d'une application ou d'un sujet.
- Couvrir par des tests les points d'accès dont dépend le métier.
Voir aussi
- Connecteurs — le connecteur lui-même : adresse, authentification, environnements.
- Un écran sur un point d'accès d'API · Services · Tests
- API REST