Non capisco perché non esista una documentazione completa per tutti gli endpoint API. La documentazione originale è stata resa pubblica nel dicembre 2014 e, sei anni dopo, la documentazione è ancora incompleta.
Perché è così? La mancanza di una buona documentazione e il suggerimento di effettuare il reverse engineering dell’API costituiscono un ostacolo significativo per gli sviluppatori che desiderano utilizzare l’API.
Cordiali saluti,
Uno sviluppatore frustrato
Puoi fornire alcuni esempi di ciò con cui hai difficoltà o che trovi carente?
Questo è un argomento di attualità perché ho un avviso sul mio forum: “Abbiamo rilevato una richiesta API che utilizza un metodo di autenticazione deprecato”.
Vorrei sapere qual è il metodo attuale da utilizzare e avere una guida passo passo per implementarlo dal punto di vista dell’amministratore del forum.
Ciò che ho trovato sono discussioni datate che rimandano a GitHub e, in quanto persona non tecnica, i riferimenti al codice non mi sono utili. Qualcuno può fornire indicazioni in linguaggio semplice?
L’autenticazione corretta dell’API è trattata nella documentazione, proprio in cima. In breve, devi utilizzare le intestazioni HTTP per fornire la chiave API e il nome utente invece dei parametri dell’URL.
@justin Il mio esempio specifico è che sto lentamente lavorando al rilascio di un wrapper Python per l’API di Discourse e trovo la mancanza di una documentazione adeguata schiacciante. Devo già testare manualmente ogni singolo endpoint, ma molti di questi non sono documentati o sono documentati in modo errato.
È esplicitamente dichiarato in cima alla documentazione che l’API non è completamente documentata. Voglio sapere: Perché?
Vedi Reverse engineer the Discourse API
Perché ogni granello di sabbia su una spiaggia non è “completamente documentato”? 
Per pura curiosità, perché non supportare semplicemente ciò che è necessario fino a quando non si incontra un nuovo requisito non supportato, per poi analizzarlo al contrario? È molto più facile che puntare al 100% ed è inutile incapsulare chiamate che non verranno mai utilizzate? Soprattutto considerando che dovrete supportare un bersaglio in continua evoluzione. Non vi faciliterebbe la vita?
Capisco che questo possa essere reverse-engineerato. È solo un po’ frustrante doverlo fare. L’API è stata creata da esseri umani che devono sapere come funziona: perché non possono scriverlo in modo che altri ne siano informati?
Non credo che sia una richiesta eccessiva. Una buona documentazione è fondamentale in qualsiasi progetto.
Al momento questo è il piano: ho già specchiato ogni endpoint documentato nel mio repository, nel ramo develop, e sono arrivato al punto in cui dovrò iniziare a fare reverse engineering.
Sto già iniziando a contribuire a GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub, ma mi chiedo davvero perché sia necessario su un progetto così consolidato.
Come per qualsiasi cosa, si tratta di risorse e priorità. La superficie dell’API è enorme. Tecnicamente, è tutto: tutto viene accessibile tramite l’API, ecco perché funziona l’ingegneria inversa. Abbiamo scelto di concentrare il nostro tempo di ingegneria limitato su correzioni, funzionalità, prestazioni, ecc., piuttosto che sulla documentazione. La direzione del nostro prodotto è in gran parte guidata dai nostri clienti e dalla nostra comunità. Per quanto ne so, nessun cliente ha mai richiesto una copertura del 100% della documentazione dell’API. Quando i clienti chiedono qualcosa che manca o non è chiaro, lo aggiungiamo. Pertanto, la copertura del 100% non è stata una priorità.
Al momento, la documentazione dell’API è curata manualmente. Questo è ovviamente un metodo non sostenibile, ma al momento è quello che abbiamo. La ristrutturazione del sistema di documentazione dell’API per renderlo generato in modo programmatico è un elemento “da fare”, ma non è attualmente previsto per alcuna versione specifica, quindi non esiste una tempistica per il completamento.