search

etalab / admin_api_entreprise

Site vitrine / backoffice de API Entreprise
https://entreprise.api.gouv.fr
MIT License
9 stars 5 forks source link

Documentation API Particulier comme API Entreprise #912

Closed Haelle closed 1 year ago

Haelle commented 1 year ago
skelz0r commented 1 year ago

On attend la v3 d'API Particulier ici ? (histoire d'harmoniser)

Haelle commented 1 year ago

j'ai recalé ce chantier pour le T1 et détaillé les différents chantiers qui sont nécessaires

skelz0r commented 1 year ago

Le MVP c'est importer https://api.gouv.fr/les-api/api-particulier + les N cas d'usages + les endpoints. Tout le reste c'est anecdotique dans une v1.

skelz0r commented 1 year ago

(d'ailleurs on pourrait même s'arrêter à juste importer la page ci-dessus)

DorineLam commented 1 year ago

Je profite de cette issue pour vous lister les éléments qui me paraissent importants pour gérer l'arrivée d'un front API Particulier de façon efficace par rapport au front API Entreprise :

@skelz0r @Charlottecho @mazalaigue (@Haelle)

Les points de vigilance côté user :

Avoir des parcours centrés cas d'usages, ciblés et clairs

C'est un impératif, il faut que les cas d'usages des données des particuliers ne soit pas pollués par les cas d'usage des données des entreprises et vice versa. On a déjà cette question qui peut se poser avec les associations, même si c'est à une échelle différente.

Pour ça : deux sites séparés ça marche, mais je ne vois pas en quoi il ne serait pas possible de faire 1 seul site, avec la possibilité de "filtrer" : On pourrait même imaginer faire une page d'accueil différente pour mieux cibler les usagers, page qui filtre simplement le catalogue et les cas d'usages : Je pense par exemple à annuaire des entreprises qui est en train de créer des pages d'accueil différentes en ayant filtré son annuaire.

Prendre en compte la structuration des services de nos FS

Je ne suis pas convaincue que les services de nos FS sont découpés par type d'usagers. Ce n'est en tout cas pas ce que j'ai pu observer durant divers échanges. Ils sont certainement découpés par types de démarches (exemples : pôle des aides et subventions, pôle commande publique) : sauf le pôle commande publique qui est 100% concerné par l'API Entreprise, le pôle des aides peut concerner aussi des particuliers, car les collectivités délivrent des aides aux particuliers.

@Charlottecho je suis très preneuse de ton avis là-dessus car maintenant, c'est toi qui a le plus grand panel d'usager en tête.

Mes remarques :

Voir les autres API fait potentiellement de nos utilisateurs des prescripteurs

Certes, nos FS ne gèrent pas forcément tous les types d'usagers (citoyens, assos, entreprises) mais par contre, leurs administrations, elles, sont souvent confrontées aux 3. Donc en mettant au même endroit les API, on permet de faire circuler l'information qu'elles existent.

Informer très clairement nos utilisateurs que les données des particuliers sont hypers sensibles et donc sous conditions d'utilisation spécifiques

C'est le point qui pourrait me faire pencher pour avoir 2 sites, mais est-ce que ce ne serait pas également gérable avec 1 site commun :

Les points de vigilance côté nous :

Ne pas avoir à dupliquer et donc maintenir un contenu qui est identique de part et d'autres :

Si on fait un site commun, on va forcément avoir quelques éléments à penser pour pouvoir adapter quelques zones de contenu spécifiques mais ça me semble vraiment mineur

Ne pas avoir à gérer des templates a deux endroits qui sont structurellement identiques :

Je n'ai aucune idée de si 1 ou 2 sites à un impact sur ce point.

Ne pas avoir à faire des commits dans des dépôts différents.

Déjà gérer Siade et admin c'est un enfer pour moi ... Quand je veux modifier la doc je dois aller à deux endroits différents, ça me prend à chaque fois deux fois plus de temps. Je dois demander deux mises en prod ...

Mailjet - Ne pas avoir à gérer deux templatings d'e-mails

J'ai peur rien que d'y penser. Vraiment, il faut que les templates soient identique pour les deux, et donc qu'on arrête d'avoir un header API Entreprise OU API Particulier.

Si on a deux sites, je crains qu'il faille avoir des templates différents car tous les liens seront différents.

skelz0r commented 1 year ago

J'ai une idée assez claire et arrêtée de si on doit fusionner ou non les 2: pour moi le site vitrine des API est déjà géré par un site : api.gouv.fr.

L'ensemble des arguments que tu avances sont déjà taclés par api.gouv.fr:

  1. Cas d'usages => y'a déjà une présentation sur ce service des cas d'usages par API
  2. Structuration des FS => besoin d'une API de l'état ? Je vais sur api.gouv.fr, et je cherche là dessus (api geo, éducation national, etc etc..). Ici clairement y'a moyen qu'ils utilisent d'autres API de l'état

A court/moyen terme mon avis ici n'importe peu car dans tous les cas, que l'on décide ou non de faire un site commun pour moi il faut harmoniser notre gestion de la documentation que ce soit sur API Entreprise ou API Particulier. La première étape naturelle est de faire un site iso avec API Entreprise car toutes les specs sont déjà posées.

D'ailleurs à la lumière de ce que tu écris, je crois qu'il y a un point à clarifier tout de suite: actuellement le dépôt https://github.com/etalab/admin_api_entreprise accueil le site vitrine d'API Entreprise ET d'API Particulier (pour le moment ce dernier ne fait que de la connexion + le listing des jetons). L'objectif pour moi ici est de continuer comme ça et ainsi partager tout ce qui est partageable entre les 2 sites. Typiquement:

  1. Le backoffice => stats jetons, listing des jetons, liens datapass, contacts etc etc => quasiment déjà le cas, j'ai juste fait un truc KISS
  2. Le catalogue => y'a 0 raison qu'on split et duplique en 2 trucs différents 🤷
  3. La structure des cas d'usages => c'est déjà pensé pour API Entreprise, on importe ceux d'API Particulier et c'est tout

Et pour terminer: qu'on décide de faire 1 ou 2 sites, ça sera de toute façon la même codebase à la fin, donc tout ce qui sera partageable on le partagera (i.e. on ne fera pas de duplication inutile).

Petit point pour Mailjet: askip avec l'homologation de sécurité faudra sortir de mailjet, mais bonne nouvelle ici, vu qu'on a fait les templates on peut les télécharger en mjml ( https://mjml.io/ ) et ici juste refacto le tout et ainsi faire en sorte que modifier un header modifie tous les headers de mail.

Petit aparté:

Ne pas avoir à faire des commits dans des dépôts différents.

Déjà gérer Siade et admin c'est un enfer pour moi ... Quand je veux modifier la doc je dois aller à deux endroits différents, ça me prend à chaque fois deux fois plus de temps. Je dois demander deux mises en prod ...

Oui c'est une vraie plaie, d'où mon militantisme pour merger les 2 sites, je pense que je gagnerai facilement x2 en efficacité ici 🙄 Et clairement j'ai 0 envie de maintenir 2 sites vitrines différents alors que c'est ~ish la même chose

skelz0r commented 1 year ago

Après discussion avec Dorine, on est aligné là dessus.

Samuelfaure commented 1 year ago

Swagger api-part fait dans PR https://github.com/etalab/siade/pull/608

Charlottecho commented 1 year ago

Mon regard : 1-J’irai vers 1 seul site api particulier ( avec fiche api.gouv simple qui redirige vers le site car trafic encore important sur api.gouv) pour les raisons énoncées :

2- "Je ne suis pas convaincue que les services de nos FS soient découpés par type d’usagers". Plus complexe que cela :

Niveau communication/Bizdev :

DorineLam commented 1 year ago

Top on est toutes et tous alignés :)

Haelle commented 1 year ago

On est bon là dessus on peut clore ? (si oui fermez l'issue dans la foulée)

DorineLam commented 1 year ago

Oui c'est bon :)