Я не понимаю, почему полные документация для всех конечных точек API отсутствует. Оригинальная документация была опубликована для общественности в декабре 2014 года, а прошло уже 6 лет, и документация по-прежнему не завершена.
Почему так происходит? Отсутствие качественной документации и предложение реверс-инжиниринга API являются значительным барьером для разработчиков, желающих использовать API.
С уважением,
Разочарованный разработчик
Можете ли вы привести примеры того, с чем у вас возникают трудности или чего вам не хватает?
Это актуальная тема, так как на моём форуме появилось предупреждение: «Обнаружен API-запрос, использующий устаревший метод аутентификации».
Мне хотелось бы узнать, какой метод следует использовать сейчас, и получить пошаговое руководство по его внедрению с точки зрения администратора форума.
Всё, что я нашёл, — это устаревшие обсуждения со ссылками на GitHub, а для нетехнического специалиста ссылки на код не приносят пользы. Не могли бы вы дать разъяснения простым языком?
Правильная аутентификация в API описана в документации, прямо в начале. Кратко: вам нужно использовать HTTP-заголовки для передачи ключа API и имени пользователя вместо параметров URL.
@justin Мой конкретный пример: я медленно работаю над созданием Python-обёртки для API Discourse, и отсутствие полноценной документации меня просто ошеломляет. Мне уже приходится вручную тестировать каждую точку доступа, но многие из них либо не описаны, либо описаны неверно.
В самом верху документации прямо указано, что API документирован не полностью. Я хочу знать: почему?
См. Reverse engineer the Discourse API
Почему каждая песчинка на пляже не «полностью задокументирована»? 
Из любопытства: почему бы вам просто не поддерживать то, что требуется, пока не появится новая неподдерживаемая функция, которую тогда можно будет реверс-инженерить? Это гораздо проще, чем стремиться к 100% покрытию, и бессмысленно оборачивать вызовы, которые никогда не будут использоваться? Тем более что вы поддерживаете постоянно меняющуюся цель. Упростите себе жизнь?
Я понимаю, что это можно реверс-инжинирить. Просто немного раздражает необходимость делать это. API был создан людьми, которые должны знать, как он работает. Почему эти люди не могут записать это, чтобы другие могли быть проинформированы?
Мне не кажется, что это слишком много просить. Хорошая документация критически важна в любом проекте.
Таков план на данный момент: у меня уже есть все задокументированные эндпоинты, отражённые в моём репозитории в ветке develop, и я дошёл до точки, где мне придётся начать обратное проектирование.
Я уже начинаю вносить вклад в GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub, но меня действительно беспокоит, почему это вообще необходимо в таком устоявшемся проекте.
Как и в любом деле, всё упирается в ресурсы и приоритеты. Поверхность API огромна. Технически это всё — ко всему осуществляется доступ через API, поэтому и работает обратная разработка. Мы решили направить наше ограниченное время инженеров на исправления, новые функции, производительность и т. д., а не на документацию. Направление развития нашего продукта в значительной степени определяется нашими клиентами и сообществом. Насколько мне известно, ни один клиент никогда не требовал 100% покрытия документации API. Когда клиенты спрашивают о чём-то отсутствующем или непонятном, мы это добавляем. Поэтому 100% покрытие не было приоритетом.
На данный момент документация API вручную курируется. Очевидно, что это неустойчивый метод, но пока это то, что у нас есть. Рефакторинг системы документации API для её программной генерации — это задача «на будущее», но она пока не запланирована ни для какого конкретного релиза, поэтому сроков завершения нет.