Je ne comprends pas pourquoi une documentation complète pour tous les points de terminaison de l’API n’existe pas. La documentation originale a été publiée au public en décembre 2014, et voici que nous sommes six ans plus tard, et la documentation est toujours à moitié aboutie.
Pourquoi en est-il ainsi ? Le manque de bonne documentation et la suggestion de procéder à une ingénierie inverse de l’API constituent un obstacle majeur pour les développeurs souhaitant utiliser l’API.
C’est un sujet d’actualité car j’ai reçu une alerte sur mon forum : « Nous avons détecté une requête API utilisant une méthode d’authentification obsolète. »
J’aimerais savoir quelle méthode je dois utiliser actuellement et obtenir un guide pas à pas pour la mettre en place, du point de vue de l’administrateur du forum.
Ce que j’ai trouvé jusqu’ici, ce sont des discussions datées pointant vers GitHub, et en tant que personne non technique, les références au code ne m’aident pas. Quelqu’un pourrait-il fournir des explications en langage simple ?
L’authentification correcte de l’API est traitée dans la documentation, tout en haut. En bref, vous devez utiliser les en-têtes HTTP pour fournir la clé API et le nom d’utilisateur au lieu des paramètres d’URL.
@justin Mon exemple concret est que je travaille lentement sur le déploiement d’un wrapper Python pour l’API Discourse, et je trouve le manque de documentation appropriée accablant. Je dois déjà tester manuellement chaque point de terminaison, mais beaucoup de ces points de terminaison ne sont soit pas documentés, soit mal documentés.
Il est explicitement indiqué en haut de la documentation que l’API n’est pas entièrement documentée. Je veux savoir : Pourquoi ?
Par curiosité, pourquoi ne pas simplement prendre en charge ce qui est nécessaire jusqu’à ce que vous rencontriez une nouvelle exigence non prise en charge, moment auquel vous l’analysez à rebours ? C’est beaucoup plus facile que de viser 100 % et il est inutile d’envelopper des appels qui ne seront jamais utilisés ? Surtout que vous serez amené à prendre en charge une cible mouvante. Rendez-vous la vie plus facile ?
Je comprends que cela puisse être décompilé. C’est juste un peu frustrant de devoir faire cela. L’API a été créée par des humains qui doivent savoir comment elle fonctionne ; pourquoi ces humains ne peuvent-ils pas la documenter afin que d’autres soient informés ?
Je ne pense pas que ce soit une demande excessive. Une bonne documentation est cruciale dans tout projet.
C’est le plan pour le moment : j’ai déjà reflété tous les points de terminaison documentés dans mon dépôt, sur la branche develop, et j’en suis arrivé au point où je vais devoir commencer à faire de l’ingénierie inverse.
Comme pour tout, il s’agit de ressources et de priorités. La surface de l’API est énorme. Techniquement, c’est tout : tout est accessible via l’API, d’où la raison pour laquelle le reverse engineering fonctionne. Nous avons choisi de concentrer notre temps d’ingénierie limité sur les corrections, les nouvelles fonctionnalités, les performances, etc., plutôt que sur la documentation. La direction de notre produit est largement pilotée par nos clients et notre communauté. À ma connaissance, aucun client n’a jamais demandé une couverture de 100 % de la documentation de l’API. Lorsque les clients posent des questions sur quelque chose qui manque ou qui est peu clair, nous l’ajoutons. Par conséquent, une couverture à 100 % n’a pas été une priorité.
Pour le moment, la documentation de l’API est gérée manuellement. Cela n’est évidemment pas une méthode durable, mais c’est ce que nous avons pour l’instant. Refactoriser le système de documentation de l’API pour qu’il soit généré de manière programmatique est une tâche à faire, mais elle n’est actuellement prévue pour aucune version spécifique, il n’y a donc pas de calendrier de réalisation.
