Petites amélioration de la documentation de l'api #4815
Conversation
| - `endpoint` est le nom du point de terminaison | ||
|
|
||
| Par exemple, on aura : `https://<domain>/api/v1/absences` | ||
|
|
There was a problem hiding this comment.
ce passage est un bon exemple de description très longue pour dire des choses très simples : c'est l'api v1, et les routes sont explicites dans tout le reste de la doc
| @@ -1,10 +1,9 @@ | |||
| L'API de RDV-Solidarités vous permet de lire des données dans notre base depuis votre logiciel. | |||
| L'API de RDV Service Public permet à nos partenaires, comme par exemple Démarches Simplifiées et RDV Insertion,d'ajouter de la gestion de rendez-vous dans leurs applications métier. | |||
| Elle peut aussi être utilisée pour synchroniser les calendriers des agents de votre administration avec ceux qu'ils ont sur leur compte RDV Service Public. | |||
There was a problem hiding this comment.
La doc de l'api étant visible par des partenaires potentiels, c'est bien qu'ils puissent se projeter un peu plus sur ce qu'elle permet de faire.
|
|
||
| # Dépréciations |
There was a problem hiding this comment.
j'ai déplacé cette section à la fin de la doc. Ça fait longtemps que cette dépréciation existe, et c'est sans doute pas ce qu'on veut mettre en avant pour nos nouveaux partenaires
| Pour la version production, les requêtes doivent être adressées à https://www.rdv-solidarites.fr et non à https://rdv-solidarites.fr. | ||
|
|
||
| Pour la version démo, les requêtes doivent être adressées à https://demo.rdv-solidarites.fr. | ||
|
|
||
| # Authentification | ||
|
|
||
| Certains points de terminaison sont réservés aux agents authentifiés, dans la limite de leur rôle au sein de l'application. | ||
| Presque tous les points de terminaison sont réservés aux agents authentifiés, dans la limite de leur rôle au sein de l'application. |
There was a problem hiding this comment.
un seul endpoint ne nécessite pas d'authentification (public_links)
| target_url: target_url, | ||
| secret: secret, | ||
| subscriptions: %w[rdv user user_profile organisation motif lieu agent agent_role] | ||
| ) |
There was a problem hiding this comment.
c'était une bonne occasion de faire tourner un seul test (à la place de 5), mais de garder le même niveau de détail des messages d'erreur avec ce matcher (plus de signal et moins de bruit dans le fichier de test, et ça permet de générer la doc plus rapidement)
| @@ -52,7 +52,7 @@ | |||
| "v1/api.json" => { | |||
| openapi: "3.0.1", | |||
| info: { | |||
| title: "API RDV Solidarités", | |||
| title: "API de RDV Service Public", | |||
There was a problem hiding this comment.
Pour les partenaires qui arrivent depuis la landing page de RDV Service Public (qui est en plus notre marque principale), c'est quand même mieux de voir ce titre
Co-authored-by: Adrien Di Pasquale <[email protected]>
Co-authored-by: Adrien Di Pasquale <[email protected]>
victormours
force-pushed
the
small-api-simplifications
branch
from
b557dc1
to
038c574
Compare
Contexte
La nouvelle homepage sur rdv.anct.gouv.fr met en avant la documentation de notre API, et les discussions avec Démarches Simplifiées et Mon Suivi Social nous amènent à leur passer des liens vers notre documentation.
Le problème, c'est que ça fait longtemps qu'on ne s'était pas trop penché dessus, et il y a pas mal d'inexactitudes. Le but de cette PR est donc de passer un petit coup de frais sur cette documentation.
Certains passages ont été écrits par des devs qui étaient juste de passage, et qui avait une vision pour cette api qui ne s'est pas concrétisée.
Cette PR n'est pas une nouvelle version parfaite, mais elle est une amélioration raisonnable pour un vendredi de cooldown.