# L'API (crisalid-apollo)

import { Mermaid } from "../../../../src/components/Mermaid";

> **En bref :**
> L'API est le guichet par lequel les applications, SoVisu+ en tête, interrogent le graphe sans y accéder directement. Elle tourne sur l'instance de développement.
> Elle **ne convient pas telle quelle à une vitrine** : une clé unique y ouvre la lecture **et** l'écriture, et elle ne produit aucun export.

## Ce que c'est et à qui ça sert

L'API (crisalid-apollo) expose le graphe dans un langage de requête courant pour les applications web, GraphQL. Une application y demande, par exemple, « les publications de telle personne avec leurs coauteurs » et reçoit une réponse structurée.

Elle sert d'abord à **SoVisu+**, qui s'en sert pour afficher et tenir à jour sa copie de travail. Elle n'a ni base propre ni règle métier : elle est **générée automatiquement** à partir d'une description du modèle de données écrite à la main dans le dépôt, qui doit suivre les évolutions du graphe. Elle ne moissonne rien et ne rapproche rien.

## Ce qui se passe dedans

<Mermaid
  title="Une requête à l'API"
  caption="L'API traduit la requête en lecture du graphe. Le même schéma généré contient aussi des opérations d'écriture, ouvertes par la même clé."
  chart={`flowchart TB
    A["Application<br/>SoVisu+ aujourd'hui"]
    K{"Clé d'API valide ?"}
    S["Schéma généré<br/>à partir du modèle"]
    G[("Le graphe")]
    R["Réponse structurée"]
    A --> K
    K -->|"oui"| S --> G
    G --> R --> A
    K -->|"non"| X["Refus"]`}
/>

Le schéma décrit personnes, structures, identifiants, documents, notices sources, contributions, revues et concepts. Qu'un champ y soit déclaré ne prouve ni qu'il est rempli dans le graphe, ni qu'il est publiable.

## Ce qu'on a observé

| Constat | Statut | Source |
|---|---|---|
| **Une clé d'API unique qui ouvre aussi les écritures** : le schéma généré compte 60 opérations de lecture et 60 d'écriture, sans clé limitée à la lecture. Détail réservé à l'équipe CRISalid | Confirmé | [sécurité, droits, données personnelles](/03-crisalid/03-fonctionnement-transversal/securite-droits-donnees-personnelles) |
| Aucune règle métier ni fichier d'export : l'API répond requête par requête | Confirmé | [contrats API et événements](/03-crisalid/01-donnees/contrats-api-evenements) |
| Le schéma est écrit à la main, à côté du graphe : il doit suivre ses évolutions | Confirmé | [schéma du dépôt](https://github.com/CRISalid-esr/crisalid-apollo/blob/d377579a/src/schema.ts) |
| Licence CeCILL 2.1 dans le fichier de licence ; les métadonnées du paquet indiquent encore une autre licence, à faire corriger | Confirmé | [exploitation et gouvernance](/03-crisalid/03-fonctionnement-transversal/exploitation-et-gouvernance) |
| Pas de documentation officielle dédiée | Confirmé | [dépôt](https://github.com/CRISalid-esr/crisalid-apollo) |
| Le service tourne ; son schéma n'a pas été récupéré | Observé sur instance (dev) | [ce que montre l'instance](/03-crisalid/06-instance-saclay/00-ce-que-linstance-demontre) |

## Pour la vitrine

- ***Apporte*** : un accès structuré et documenté par son schéma à tout le graphe, déjà utilisé par SoVisu+ ; un service d'export pourrait s'en servir pour lire.
- ***Prouvé*** : l'API tourne sur l'instance ; son contrat a été régénéré et contrôlé à partir du code.
- ***Bloque ou reste à prouver*** : donner la clé à une vitrine reviendrait à lui donner le droit d'écrire dans le graphe. Il faut donc **un service d'export dédié**, en lecture seule, qui produit l'extrait et n'expose que les champs publiables ; les règles de filtrage (suppressions, coauteurs externes, données personnelles) y sont appliquées. Ce service n'existe pas.

## Liens

- Dépôt officiel : [github.com/CRISalid-esr/crisalid-apollo](https://github.com/CRISalid-esr/crisalid-apollo)
- Documentation officielle : aucune page dédiée ; le dépôt contient un guide d'installation
- Pages qui font foi : [sécurité, droits, données personnelles](/03-crisalid/03-fonctionnement-transversal/securite-droits-donnees-personnelles) ; [contrats API et événements](/03-crisalid/01-donnees/contrats-api-evenements)

Révision lue : `d377579a`