Una nuova API Python

Sviluppatore
1

Sono felice di condividere fluent-discourse, un nuovo pacchetto Python per l’utilizzo dell’API di Discourse.

Esistono già alcuni pacchetti per interagire con l’API di Discourse tramite Python. Allora perché crearne un altro?

Gli altri pacchetti per Discourse disponibili tendono ad affrontare il problema in modo simile: creare una funzione Python unica per ogni endpoint dell’API.

Questo approccio presenta alcuni svantaggi:

  1. È molto difficile raggiungere la piena parità di funzionalità con l’API. L’API di Discourse è parzialmente scarsamente documentata e spesso è necessario analizzare al contrario gli endpoint. Inoltre, esistono numerosi plugin che espongono endpoint API che non fanno nemmeno parte del core. Questo pone l’utente della libreria di fronte alla difficile scelta di aprire richieste di pull per aggiungere gli endpoint necessari alla libreria, oppure costruire una soluzione personalizzata per gli endpoint aggiuntivi.
  2. Devi imparare un’altra API. Oltre a imparare i metodi e gli endpoint dell’API di Discourse, devi capire quale sia la chiamata alla funzione corrispondente in Python.
  3. C’è molto più codice da testare, quindi è più difficile ottenere una copertura dei test del 100%. Di conseguenza, c’è meno fiducia nella qualità del software prodotto.

In contrasto con questo approccio, ho utilizzato un’interfaccia “fluent”, in cui si usa la concatenazione di metodi per costruire le richieste. Facciamo un esempio.
Per ottenere gli ultimi argomenti in una categoria ‘foo’ con id=5, si utilizza questo endpoint:
GET /c/foo/5.json.
Per eseguire quella richiesta con questa libreria, basta chiamare:
client.c.foo[5].json.get()

Come puoi vedere, c’è una parità semantica tra l’endpoint dell’API e la chiamata corrispondente in Python.

Questo approccio:

  1. Offre immediatamente la piena parità di funzionalità con l’API di Discourse, inclusi gli endpoint non documentati, gli endpoint provenienti da plugin e gli endpoint che dovranno ancora essere definiti (future-proof).
  2. Devi imparare solo l’API di Discourse. È facile tradurre qualsiasi chiamata API in questo modo, quindi non hai bisogno di cercare la funzione che corrisponde.
  3. L’intera libreria è composta da circa 150 righe di codice. Questo rende banale ottenere una copertura dei test del 100%.

Esiste una copertura dei test del 100% con una manciata di test di integrazione eseguiti contro un server Discourse attivo.

Se tutto ciò ti sembra interessante, spero che proverai questo pacchetto!

21 Mi Piace
3

È un approccio interessante…

Per fare qualcosa di simile in PHP dovremmo affidarci ai metodi magici, perdendo così il vantaggio dell’autocompletamento dell’IDE e simili. Ma potrebbe essere un prezzo che vale la pena pagare.

Qual è il vantaggio di questo approccio rispetto al semplice passaggio dell’URL come argomento: client.get(url)?

4

È un buon punto: l’autocompletamento dell’IDE non sarà di grande aiuto in questo caso. Potrebbe valere la pena utilizzare una libreria diversa se per te è importante.

Poiché ogni catena di metodi restituisce un nuovo client, un vantaggio che mi viene in mente è poter memorizzare una specifica catena di metodi in una variabile e riutilizzarla per chiamate successive. Ad esempio, supponiamo di avere una lista di dati per nuovi post che si desidera creare.

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

Potresti memorizzare la catena di metodi “Nuovo post” e riutilizzarla per creare ciascuno dei post nell’elenco.

new_post_endpoint = client.posts.json

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

Potresti immaginare altri scenari in cui questa capacità di riutilizzare un client potrebbe essere utile. Oltre a questo, non c’è un grande vantaggio rispetto al semplice passaggio dell’URL come hai suggerito. Ti invito a leggere la documentazione della libreria Universal Client, che contiene alcune informazioni sulla logica alla base di questo tipo di approccio.

Inoltre, per un’implementazione specifica di questo approccio in PHP, consulta l’API PHP di SendGrid. Mi sono ispirato a costruire questa soluzione quando ho letto dell’API Python di SendGrid.

3 Mi Piace