API du serveur¶
L'API HTTP du serveur, décrite en fichiers OpenAPI (Swagger 2.0), un par service. Cet index dit quel dossier contient quoi et comment un appel s'authentifie ; les fichiers eux-mêmes sont la référence.
| Partie | Contenu |
|---|---|
| API publique | Ce qu'un utilisateur connecté peut faire : parcourir, lire, collectionner, demander. |
| API d'administration | L'administration du serveur : configuration, transcodage, sauvegardes, métadonnées, utilisateurs. |
| API des plugins | La gestion des plugins, les webhooks, et les préférences que l'interface d'un plugin garde par utilisateur. |
Chaque fichier .swagger.json s'importe dans n'importe quel outil OpenAPI
(Swagger UI, Postman, Insomnia). Les routes HTTP sont générées à partir des
définitions gRPC de proto/evey/v1/ : un nom de méthode dans un fichier est
la méthode gRPC qui se trouve derrière.
Authentification¶
Trois sortes d'identifiants atteignent l'API, tous dans l'en-tête
Authorization :
| Identifiant | Qui | Comment |
|---|---|---|
| Jeton de session | Une personne connectée par une application | Bearer <jeton>, obtenu à la connexion et renouvelé par l'application. |
| Clé d'API | Un script, au nom de l'administrateur qui l'a créée | Bearer evey_... (le préfixe Bearer est facultatif). À permissions limitées, révocable : Webhooks et clés d'API. |
| Jeton de plugin | L'interface d'un plugin, par la page hôte | Émis pour cinq minutes, pour un plugin et un utilisateur, ne portant que les portées public et prefs accordées au plugin ; toute autre méthode le refuse. Le cadre ne le détient jamais : la page hôte relaie les appels. |
Un jeton de plugin ne peut jamais atteindre une méthode d'administration, quelles que soient ses portées (ADR-0003, ADR-0012).
Régénération¶
Pour les contributeurs : les fichiers sont régénérés à partir des définitions protobuf.