Metodo programmatico per ottenere tutti gli endpoint API per la mia istanza

[RGJ (Richard - Communiteq)]

@mcwumbly

Quindi, quali garanzie di stabilità possiamo offrire per la nostra API backend?

Penso che questa sia una responsabilità che la documentazione dell’API dovrebbe affrontare.

Le garanzie di stabilità dovrebbero essere affrontate con un semplice versionamento dell’API.

@mcwumbly

Innanzitutto, come modello mentale di alto livello, descriverei le cose in questo modo:

• Il nostro punto di ingresso principale per la documentazione è qui, come hai sottolineato: Documentation - Discourse Meta
• Per la documentazione per sviluppatori, è qui, o forse ancora meglio, qui: Introduction to Discourse Development
• La documentazione API è un sottoinsieme della documentazione per sviluppatori e si trova qui: https://docs.discourse.org/

Chiamerei la documentazione API docs piuttosto che specs, ma concordo sul fatto che siano comunque un sottoinsieme della nostra documentazione per sviluppatori. L’URL per tale documentazione è strano… avrebbe più senso che la nostra documentazione completa risiedesse lì o che fosse un reindirizzamento a Documentation - Discourse Meta, e che ci fosse un chiaro segnale da Introduction to Discourse Development alla documentazione API.

Questo argomento non riguarda dove si trova la documentazione, ma come viene documentata l’API. Ciò che manca è un formato standardizzato e leggibile dalla macchina come OpenAPI.

Questa assenza, insieme alla mancanza di versionamento, rende il lavoro di integrazione più difficile e fragile di quanto dovrebbe essere. Anche uno schema OpenAPI di base per gli endpoint documentati sarebbe molto utile.