Программный способ получения всех конечных точек API для моего экземпляра?

[RGJ (Richard - Communiteq)]

@mcwumbly

Так какие гарантии стабильности мы можем давать в отношении нашего бэкенд-API?

Думаю, это вопрос, который должны поднимать эти документация по API.

Гарантии стабильности должны обеспечиваться простым версионированием API.

@mcwumbly

Во-первых, как некая более высокоуровневая ментальная модель, я бы описал это так:

• Наш основной входной пункт для документации находится здесь, как вы отметили: Документация — Discourse Meta
  • Для документации разработчика она находится здесь, или, возможно, ещё лучше — здесь: Введение в разработку Discourse
    • Документация по API является подмножеством документации для разработчиков и расположена здесь: https://docs.discourse.org/

Я бы называл документацию по API именно документацией, а не спецификациями, но согласен, что она всё равно является частью нашей документации для разработчиков. URL этой документации кажется странным… было бы логичнее разместить там полную документацию или сделать перенаправление на Documentation - Discourse Meta, а также обеспечить чёткую ссылку с Введения в разработку Discourse на документацию по API.

Эта тема не о том, где находится документация, а о том, как документирован API. Не хватает стандартизированного, машиночитаемого формата, такого как OpenAPI.

Отсутствие такого формата, наряду с отсутствием версионирования, делает работу по интеграции более сложной и хрупкой, чем это должно быть. Даже базовая схема OpenAPI для документированных конечных точек была бы очень полезна.