Portail Client : documentation interactive, SDK et sandbox

Construire des applications sur Ontologie ne devrait pas necessiter de lire des centaines de pages de documentation technique. Le nouveau Portail Client offre une experience de developpeur complete : documentation interactive avec exemples executables, SDK TypeScript et Python prets a l'emploi, et sandbox pour tester vos integrations sans toucher a la production.

Pourquoi un Portail Client

Jusqu'ici, integrer Ontologie dans vos applications necessitait de :

• Lire la reference API (centaines d'endpoints) pour trouver les bons appels.
• Ecrire manuellement les appels HTTP avec les bons headers, body et parametres.
• Tester sur votre workspace de production, avec le risque de modifier des donnees reelles.
• Gerer l'authentification, la pagination, les erreurs et les types sans assistance.

Le Portail Client elimine ces frictions en fournissant tout ce dont un developpeur a besoin en un seul endroit.

Ce qui change

Documentation interactive

Le Portail Client offre une documentation interactive ou chaque endpoint est accompagne de :

• Description claire : ce que fait l'endpoint, quand l'utiliser, quelles permissions sont necessaires.
• Parametres documentes : chaque parametre est decrit avec son type, ses valeurs possibles et des exemples.
• Exemples de code : des snippets prets a copier-coller en TypeScript, Python, curl et d'autres langages.
• Testeur integre : executez un appel API directement depuis la documentation et voyez la reponse en temps reel.
• Schemas de reponse : le format exact de la reponse, avec les types de chaque champ.

Exemple concret : vous cherchez a lister les entites de votre ontologie. Le Portail Client vous montre l'endpoint GET /api/queries/nodes, ses parametres de filtrage et de pagination, un exemple de requete en TypeScript, et vous permet de l'executer avec votre cle API pour voir les vraies donnees de votre workspace.

SDK TypeScript

Le SDK TypeScript vous permet d'interagir avec Ontologie depuis n'importe quelle application Node.js, Deno ou navigateur :

import { OntologieClient } from '@ontologie/client';

const client = new OntologieClient({
  apiKey: 'ont_live_votre_cle_api',
  workspaceId: 'votre-workspace-id',
});

// Lister les entites
const entities = await client.nodes.list({
  entityType: 'concept',
  limit: 10,
});

// Creer une entite
const newEntity = await client.commands.execute({
  type: 'CREATE_NODE',
  payload: {
    name: 'Mon entite',
    entityType: 'concept',
    position: { x: 100, y: 200 },
  },
});

Fonctionnalites du SDK :

• Typage complet : autocompletion et validation a la compilation grace aux types TypeScript generes.
• Gestion des erreurs : les erreurs API sont typees et structurees (code, message, details).
• Pagination automatique : iterez sur de grandes collections sans gerer les curseurs manuellement.
• Retry integre : les erreurs temporaires (429, 503) sont automatiquement retentees.
• Streaming : support natif du SSE pour les operations longues (invocation d'agent, execution de workflow).

SDK Python

Pour les equipes data et les notebooks Jupyter, le SDK Python offre la meme experience :

from ontologie import OntologieClient

client = OntologieClient(
    api_key="ont_live_votre_cle_api",
    workspace_id="votre-workspace-id",
)

# Lister les entites
entities = client.nodes.list(entity_type="concept", limit=10)

# Recherche semantique
results = client.search.semantic("clients avec contrat expire")

Le SDK Python est compatible avec les environnements pandas, Jupyter et les pipelines de data science.

Sandbox

La sandbox est un environnement de test isole ou vous pouvez experimenter sans risque :

• Donnees de test : la sandbox est pre-remplie avec des donnees d'exemple representant une ontologie type.
• Cle API sandbox : une cle API dediee est generee automatiquement pour la sandbox.
• Reset a la demande : remettez la sandbox dans son etat initial a tout moment.
• Memes APIs : les endpoints et le comportement sont identiques a la production — seules les donnees different.

Exemple concret : vous developpez une integration qui modifie des entites. Au lieu de tester sur votre workspace de production, vous utilisez la sandbox pour valider votre code. Une fois satisfait, vous changez la cle API pour pointer vers la production.

Packages OAuth

Pour les applications qui s'authentifient au nom d'un utilisateur (plutot qu'avec une cle API), le SDK inclut un package OAuth :

• Flux OAuth2 standard avec PKCE.
• Refresh automatique des tokens.
• Compatible avec les frameworks web courants (React, Next.js, Express).

Package React

Un package React est egalement disponible pour les applications frontend :

import { useNodes, useCommands } from '@ontologie/react';

function EntityList() {
  const { data: nodes, isLoading } = useNodes({ entityType: 'concept' });
  const { execute } = useCommands();

  const handleCreate = async () => {
    await execute({
      type: 'CREATE_NODE',
      payload: { name: 'Nouvelle entite', entityType: 'concept' },
    });
  };

  if (isLoading) return <p>Chargement...</p>;
  return (
    <ul>
      {nodes.map((node) => (
        <li key={node.id}>{node.name}</li>
      ))}
    </ul>
  );
}

Les hooks React gerent automatiquement le cache, la revalidation et les mises a jour optimistes.

Comment demarrer

1. Accedez au Portail Client via le lien dans la barre de navigation ("Portail Client") ou a l'adresse portal.ontologie-growthsystemes.com.
2. Explorez la documentation interactive : parcourez les endpoints par categorie.
3. Testez dans la sandbox : utilisez le testeur integre pour executer des appels API.
4. Installez le SDK :
   • TypeScript : npm install @ontologie/client
   • Python : pip install ontologie
5. Integrez dans votre application en utilisant votre cle API.

Prochaines etapes

• Reference API — Documentation complete des endpoints
• Cles API — Creer et gerer vos cles d'acces
• Quickstart — Premier appel API en 10 minutes
• Support — Besoin d'aide pour integrer Ontologie ?