Bibliothèque easyapi — créer des API REST en BERKIOS CODE — v1.1.0

27 commandes pour définir une API REST dans un script, la tester sans réseau (ou contre un vrai serveur), en tirer la description OpenAPI 3.1 et exporter un serveur Node.js autonome (un seul fichier, aucune dépendance). Chaque commande existe en anglais, français, espagnol et swahili (noms swahili non relus par des locuteurs natifs). Permissions demandées : fichiers (pour save-server et save-openapi, qui utilisent telecharger) et reseau (pour call-api sur un serveur désigné par set-server). Ce sont de simples macros vers les 19 commandes intégrées de la catégorie « API REST » (api-creer, api-ressource, api-route… voir la leçon formation/08) : le moteur est dans le Studio (studio/src/model/rest-api-engine.ts), pas dans la bibliothèque.

Une API en cinq lignes

quand clic
  easy-api "Boutique" "produits" "nom:texte*, prix:nombre, sku:texte*!"
  protect-api
  make-key "mobile" "ecriture" "$cle"            # le secret s'affiche une seule fois
  call-api "$r" "POST" "/api/produits" '{"nom":"Stylo","sku":"A1","prix":2}' "$cle"
  status-code "$code"                            # 201
  save-server "serveur.mjs"                      # télécharge le serveur à déployer

easy-api crée l'API Boutique et la ressource produits avec ses six routes : GET /api/produits, POST /api/produits, GET|PUT|PATCH|DELETE /api/produits/:id.

Ce que fait le moteur

• Validation à chaque écriture : types texte, nombre, entier, booleen, date (AAAA-MM-JJ), email ; * = obligatoire, ! = unique. Champ inconnu, type faux ou doublon → 422 ou 409 avec le détail par champ.
• Liste : ?limit= (1–1000, 50 par défaut), ?offset=, ?after=<id> (pagination par curseur : la réponse porte next_after tant qu'il reste des pages), ?sort=champ ou ?sort=-champ, ?q= (recherche dans les textes), ?champ=valeur (filtre). Un filtre inconnu est une erreur 400, pas ignoré.
• Routes personnalisées : route, get-route, post-route, put-route, patch-route, delete-route. La réponse est du JSON si elle commence par { ou [, sinon du texte ; {param}, {query.x}, {body.x}, {method}, {path}, {date} sont remplacés à chaque requête. Dans une réponse JSON, les valeurs injectées restent des chaînes : aucune injection possible.
• Sécurité : protect-api exige une clé (X-API-Key ou Authorization: Bearer) sur toute requête, même vers une route inconnue, sauf /health, /openapi.json et les routes marquées public. Rôles lecture (GET), ecriture (+ POST/PUT/PATCH/DELETE), admin. Les secrets ne sont jamais écrits dans la définition ni dans le serveur exporté.
• CORS : seules les origines listées par allow-origin sont autorisées ; * doit être écrit explicitement.
• Débit : rate-limit N → 429 avec Retry-After au-delà de N requêtes par minute et par client.
• Import en masse : POST /ressource/bulk (tableau JSON ou { "data": [...] }, 1 000 enregistrements au plus par requête) est atomique : tout est créé ou rien, avec l'indice de l'enregistrement fautif. seed-data accepte jusqu'à 100 000 enregistrements par appel.
• Corps limité à 5 Mo, 1 000 000 d'enregistrements par ressource (507 au-delà ; EASYAPI_MAX_RECORDS sur le serveur), 50 ressources, 200 routes, 20 clés ; en-têtes Cache-Control: no-store et X-Content-Type-Options: nosniff.

Tester, documenter, déployer

• call-api "$r" "GET" "/api/produits" appelle l'API dans le Studio, sans réseau, avec le même routeur que le serveur exporté ; status-code et response-header lisent le code et les en-têtes.
• set-server "https://api.monsite.com" désigne un vrai serveur : call-api envoie alors de vraies requêtes HTTP (mêmes arguments, mêmes codes, status-code et response-header lisent la réponse du serveur). set-server sans argument revient à l'API d'essai : un même script sert à l'essai et à la production. Le navigateur du Studio impose le CORS : le serveur doit autoriser l'origine (allow-origin).
• openapi / save-openapi "openapi.json" : description OpenAPI 3.1 (Swagger UI, Postman, générateurs de clients). Elle est aussi servie par le serveur sur /api/openapi.json.
• export-spec / import-spec : sauvegarde et rechargement de la définition (sans données ni secrets).
• save-server "serveur.mjs" (ou server-code "$code") : serveur Node.js 18+, sans dépendance.

EASYAPI_KEYS="mobile:write:UnSecretLongEtAleatoire1234" PORT=3000 HOST=0.0.0.0 node serveur.mjs

Après un arrêt brutal (kill, coupure), le journal est rejoué au redémarrage : on ne perd que les 100 dernières millisecondes. Une dernière ligne tronquée est ignorée ; une ligne corrompue au milieu du journal empêche le démarrage (rien n'est écrasé). Une API protégée refuse de démarrer sans clé. Placez toujours le serveur derrière HTTPS (Caddy, nginx…).

Limites assumées

• Les données d'essai du Studio vivent en mémoire pour la session d'aperçu et ne sont pas enregistrées dans le projet : la définition, elle, est le script (ou export-spec). easy-api / new-api repartent de zéro.
• Pas de relations entre ressources ni de transactions (sauf le lot /bulk, atomique). Gros volumes : tout reste en mémoire (≈ 1 Ko par enregistrement, 1 000 000 au plus par ressource). Accès par id, unicité et filtres d'égalité (?champ=valeur) sont indexés ; le tri est mis en cache par champ ; la pagination par curseur (after) ne coûte pas plus cher à la page 10 000 qu'à la première. La recherche ?q= parcourt les textes (linéaire) et un lot d'écritures simultanées reste sérialisé sur un seul processus. Au-delà du million, de plusieurs serveurs ou de besoins de requêtes complexes : une vraie base.
• L'instantané est relu avec JSON.parse : un fichier de données de plusieurs centaines de Mo demande autant de mémoire à la lecture.
• Pas de comptes utilisateurs : l'accès se règle par clés d'API.
• Le Studio ne peut pas ouvrir de port réseau : on teste avec call-api, puis on déploie le serveur exporté.
• Flutter : les 19 commandes api-* (donc toute la bibliothèque) existent dans l'application générée (bridge/runtime/berkios_rest_api.dart, moteur Dart pur) ; set-server + call-api y envoient de vraies requêtes HTTP (dart:io). Le moteur Dart est un simulateur local en mémoire : mêmes règles et mêmes messages, mais filtres d'égalité sans index. Ce code Dart n'a pas été compilé (ni Dart ni Flutter dans l'environnement de développement) : il est vérifié par des tests statiques et par le gabarit de serveur qu'il assemble ; à compiler au premier flutter build.

Application client-serveur

L'accueil du Studio propose la carte Application client-serveur : projet autonome (client multiplateforme) marqué architecture: "client-serveur", relié à un serveur qui héberge données et API REST. Ajoutez EasyAPI pour écrire l'API en BERKIOS CODE, exportez le serveur, puis appelez-le depuis le client.

Exemple complet

examples/application/api/client-serveur/ : une application de tâches (client BERKIOS avec easyapi, serveur Node exporté, clé d'API, import en masse, pagination par curseur). Essai sans serveur dans le Studio, puis contre serveur.mjs. Généré par node scripts/build-api-client-serveur-example.mjs.

Commandes

Cette page en Markdown · llms.txt · documentation complète pour les IA