Une nouvelle API Python

Dev
1

Je suis ravi de vous présenter fluent-discourse, un nouveau package Python pour consommer l’API Discourse.

Il existe déjà quelques packages pour interagir avec l’API Discourse via Python. Alors, pourquoi en créer un autre ?

Les autres packages Discourse disponibles tendent à aborder le problème de manière similaire : créer une fonction Python unique pour chaque point de terminaison (endpoint) de l’API.

Cette approche présente plusieurs inconvénients :

  1. Il est très difficile d’obtenir une parité fonctionnelle complète avec l’API. L’API de Discourse est partiellement sous-documentée et nécessite souvent une ingénierie inverse des points de terminaison. De plus, de nombreux plugins exposent des points de terminaison API qui ne font même pas partie du cœur du système. Cela place l’utilisateur de la bibliothèque devant un choix difficile : faire des demandes de tirage (pull requests) pour ajouter les points de terminaison dont il a besoin à la bibliothèque, ou construire une solution personnalisée pour les points de terminaison supplémentaires.
  2. Vous devez apprendre une autre API. En plus d’apprendre les méthodes et les points de terminaison de l’API Discourse, vous devez déterminer quel est l’appel de fonction correspondant en Python.
  3. Il y a beaucoup plus de code à tester, ce qui rend plus difficile d’obtenir une couverture de tests de 100 %. Ainsi, la confiance dans la qualité du logiciel produit est moindre.

Contrairement à cette approche, j’ai utilisé une interface « fluide » (fluent), où vous utilisez la chaînage de méthodes pour construire des requêtes. Prenons un exemple.
Pour obtenir les derniers sujets d’une catégorie ‘foo’ avec l’id=5, vous utilisez ce point de terminaison :
GET /c/foo/5.json.
Pour effectuer cette requête avec cette bibliothèque, appelez simplement :
client.c.foo[5].json.get()

Vous pouvez constater qu’il existe une parité sémantique entre le point de terminaison de l’API et l’appel correspondant en Python.

Cette approche :

  1. Offre dès le départ une parité fonctionnelle complète avec l’API Discourse, y compris les points de terminaison non documentés, ceux provenant de plugins, et ceux qui n’ont pas encore été définis (préparation pour l’avenir).
  2. Vous n’avez qu’à apprendre l’API Discourse. Il est facile de traduire n’importe quel appel API de cette manière, et donc vous n’avez pas besoin de rechercher la fonction qui lui correspond.
  3. L’ensemble de la bibliothèque compte environ 150 lignes de code. Cela rend trivial d’atteindre une couverture de tests de 100 %.

Il y a une couverture de tests de 100 % avec une poignée de tests d’intégration contre un serveur Discourse en direct.

Si cela vous semble attrayant, j’espère que vous essayerez ce package !

21 « J'aime »
3

C’est une approche intéressante…

Pour faire quelque chose de similaire en PHP, nous devrions nous fier aux méthodes magiques et perdre ainsi l’avantage de la complétion automatique de l’IDE, etc. Mais cela pourrait être un prix à payer qui en vaut la peine.

Quel est l’avantage de cette approche par rapport au simple passage de l’URL en tant qu’argument : client.get(url) ?

4

C’est un bon point, la complétion automatique de l’IDE ne sera pas très utile ici. Cela pourrait valoir la peine d’utiliser une bibliothèque différente si cela est important pour vous.

Puisque chaque chaîne de méthodes retourne un nouveau client, un avantage auquel je peux penser est de stocker une chaîne de méthodes spécifique dans une variable et de la réutiliser pour les appels suivants. Par exemple, supposons que vous ayez une liste de données pour de nouveaux articles que vous souhaitez créer.

post_data = [
  {
    "raw": "Hello World!",
    "topic_id": 123,
    ...
  },
  {
    "raw": "Tester",
    "topic_id": 501,
    ...
  },
  ...
]

Vous pourriez stocker la chaîne de méthodes « Nouveau article » et la réutiliser pour créer chacun des articles de la liste.

new_post_endpoint = client.posts.json

for post in post_data:
  new_post_endpoint.post(data=post)

Vous pourriez imaginer d’autres scénarios où cette capacité à réutiliser un client pourrait être utile. Au-delà de cela, il n’y a pas un grand avantage par rapport au simple passage de l’URL comme vous l’avez suggéré. Je vous encourage à lire la bibliothèque Universal Client qui contient des informations sur la justification de ce type d’approche.

De plus, pour une implémentation spécifique à PHP de cette approche, consultez l’API PHP de SendGrid. J’ai été inspiré pour construire cela en lisant l’API Python de SendGrid.

3 « J'aime »