Discourse 인스턴스에서 사용할 수 있는 API 엔드포인트의 확정된 목록을 찾는 방법을 찾고 있습니다. 플랫폼에 통합을 구축할 때 어떤 API가 사용 가능한지 파악하는 것이 때로는 어려울 수 있습니다.
기술적으로 불가능하다고 생각합니다. Discourse에는 API 탐색 경로(예: WordPress의 /wp-json 경로와 유사한 것)가 없습니다. 제가 아는 한 가장 가까운 것은 https://docs.discourse.org/ 의 문서입니다.
문서에서 다루지 않는 통합의 경우, 특정 목표를 달성하는 방법에 대해 여기에 질문하는 것이 가능한지 가장 빠르게 확인하는 방법일 것입니다. API의 일반적인 규칙은 Discourse UI를 통해 수행할 수 있는 모든 작업은 API를 통해서도 수행할 수 있다는 것입니다.
답변해 주셔서 감사합니다, 시몬! docs.discourse.org는 알고 있습니다(재밌는 점은 이게 공식 문서가 아니라 API 스펙이라는 거예요).
브라우저 콘솔을 사용해 요청을 캡처하는 방법이나 routes.rb 파일을 살펴보는 것도 익숙합니다.
하지만 상상이 되실 텐데, 위에 언급한 두 가지 방법은 상당히 번거롭고 사용자 친화적이지 않습니다. 빠른 속도로 심층적인 통합을 구축하려는 우리 같은 경우, 특히 회사 내 다른 팀이나 제3자 벤더가 통합을 원할 때… 그들에게 위와 같은 작업을 하라고 하면 반응이 매우 나빴습니다.
디스코스의 기능 유연성은 잘 알고 있지만, 이 플랫폼에서 개발하거나 통합하는 일은 솔직히 말해 쉽지 않은 싸움입니다. 마지막 수단으로, 공개된 API를 프로그래밍 방식으로 집계할 수 있는 방법이 있지 않을까 희망을 걸어 보았습니다.
소스 코드 외의 가장 확실한 참고 자료는 Discourse API 역공학입니다.
프론트엔드에서 할 수 있는 모든 작업은 API로도 수행할 수 있습니다. 반면, API에서만 수행할 수 있는 작업은 매우 적습니다.
이 부분에 대해 조금 더 자세히 설명해 주시겠어요?
Simon의 지적처럼 이 문서들은 Discourse에 확장(예: 플러그인)으로 구현된 API를 다루지 않지만, 이 문서들은 우리가 직접 관리한다는 점에서 공식 문서라고 할 수 있습니다.
서버 측 API 문서와 API 자체에 있어 개선의 여지가 적지 않다는 뜻은 아닙니다. 다만, 이미 존재하는 문서에 대한 여러분의 피드백을 조금 더 잘 이해하고 싶었습니다.
네! 요청하신 것보다 더 많은 정보를 드린 것 같네요 
여기서 공식 제품 문서를 관리하고 계신 거죠?
내 생각에는 API 스펙이 문서의 부분 집합이라는 점이 미묘한 차이인 것 같습니다. 그래서 항상 이 부분을 잊고, docs.discourse.org 링크를 누군가에게 공유했을 때 그 링크가 Discourse 문서가 아니라 제한된 API 스펙 모음으로 이어진다는 사실을 깨달을 때마다 잠시 당황하곤 합니다.
그래서 저는 다음과 같은 내용을 전합니다:
오늘 만나서 좋았고, 새로운 Netwrix 커뮤니티를 활용하여 사용자에게 어떤 경험을 제공할 수 있는지 궁금해해 주셔서 감사합니다.
실제 문서는 https://meta.discourse.org/c/documentation/10에 있습니다.
docs.discourse.org는 실제 문서가 아니라 API 스펙입니다. 새로운 커뮤니티 구축에 대한 통합을 문의해 주셨는데, 불행히도 Discourse가 제공하는 모든 기능을 보여줄 수 있는 페이지를 바로 안내해 드리기 어렵습니다. 하지만 docs.discourse.org를 방문하시면 어떤 것이 가능한지 일부 파악하실 수 있습니다.
이런 상황에서 저는 존재하는 엔드포인트의 확정된 목록을 제공해 드릴 수 없기 때문에, "상상할 수 있는 모든 것이 가능하다고 가정하세요. 제가 나가서 Discourse가 할 수 있는 일을 알아보고, 필요하면 거기서부터 범위를 좁혀가 보겠습니다"라고 말합니다.
하지만 모든 API가 스펙에 나열되어 있다면 정말 좋겠죠?
더 많은 맥락…
차를 사는데 기능 목록을 건네주면서 "좋아요! 이게 전부인가요?"라고 물으면,
"아니요… 하지만 엔진 아래를 살펴보고 12V 배선과 호스 클램프의 연결을 추적해 보면 그것이 어디로 이어지는지, 그리고 다른 어떤 기능을 하는지 역설계할 수 있을 겁니다"라고 대답한다면 이상하지 않겠습니까?
물론 이 시나리오에서 정비사/개발자/기술적인 사람들은 그렇게 할 수 있습니다. 하지만 모든 사람이 그런 것은 아닙니다 
또한 개발자로서도 저는 다음을 원하지 않습니다:
- 루트가 어디에 있을 수 있는지 확인하기 위해 Ruby를 배우는 것
- 사용 가능한 엔드포인트를 파악하기 위해 모든 routes.rb 파일을 역설계하는 것
- 역설계를 더 정교하게 하여 어떤 입력이 필요한지, 출력의 객체 구조가 어떤지 파악하는 것
- 어떤 플러그인을 가지고 있는지도 찾아보는 것
- 그들의 routes.rb 파일에 대해서도 반복하는 것 (아마도? Ruby를 모르기 때문에 실제로는 확실하지 않습니다)
- …그리고 6개월 후, 본업과 이 작업 사이에서 겨우 답을 얻는 것
저는 이 모든 것을 친근한 마음으로 말씀드립니다—오늘날 Discourse 플랫폼의 기능에 비할 수 있는 플랫폼은 없습니다. 단언합니다. 이는 시장에서 가장 강력하고, 가장 강력하며, 유연하고, 비용 대비 효율적인 제품이며, 경쟁 제품보다 한 수 위입니다.
그 단점들은 견고함, 성능, 유연함이 아닙니다. 사실, 이는 경쟁 제품들이 모방하기 힘들거나 심지어 실패할 수 있는 Discourse의 가장 큰 경쟁 우위 중 하나입니다.
- API가 훌륭하지 않아서가 아니라, 그것들을 찾는 것이 어렵기 때문입니다.
- 옵션이 많은 관리자 패널 때문에 도입이 어려운 것이 아니라, 교육 부족과
First post only처럼 모호한 관리자 설정 이름 때문이 아닙니다. - 카테고리, 토픽, 태그라는 커뮤니티 도구 구조의 견고하고도 단순한(그리고 완벽하게!) 구현이 문제인 것이 아니라, 그것이 반드시 카테고리가 아니라 블로그, 제품 공지 게시판, 아이디어 포털이 될 수 있다는 정보, 그리고 그것들이 반드시 토픽이 아니라 블로그, 제품 공지, 아이디어가 될 수 있다는 정보를 교육하고 영감을 줄 수 있는 자료가 없기 때문입니다.
제게 Discourse라는 제품이 부족한 유일한 것은 바로 마감 처리—최종적인 디테일입니다.
10점 만점에 9점, 다시 구매하겠습니다.
네, 이제 더 잘 이해가네요. 감사합니다.
아래는 제 개인적인 의견입니다. 저보다 더 knowledgeable한 분들과 상의해 보지 않았으므로, 여기서는 몇 가지 잘못 이해하고 있는 부분이 있을 수 있습니다.
우리의 스토리 문서화도 계속 발전하고 있습니다. 상당한 진전을 이루었지만, 아직 갈 길이 멉니다. 잠시 시간을 내어 상황을 정리해 보겠습니다.
먼저, 좀 더 높은 수준의 개념적 모델(mental model)로 설명하자면 다음과 같습니다:
- 문서의 주요 진입점은 여러분이 지적하신 대로 여기입니다: Documentation - Discourse Meta
- 개발자 문서는 여기에 있으며, 어쩌면 여기가 더 나을 수도 있습니다: Introduction to Discourse Development
- API 문서는 개발자 문서의 부분 집합이며, 여기에서 찾을 수 있습니다: https://docs.discourse.org/
- 개발자 문서는 여기에 있으며, 어쩌면 여기가 더 나을 수도 있습니다: Introduction to Discourse Development
저는 API 문서를 specs라기보다는 docs라고 부르겠습니다. 하지만 여전히 개발자 문서의 부분 집합이라는 점에는 동의합니다. 해당 문서의 URL이 좀 이상하네요… 전체 문서가 그곳에 있거나, https://meta.discourse.org/c/documentation/10으로 리다이렉트되고, Introduction to Discourse Development API 문서로 명확한 안내가 이루어지는 것이 더 합리적일 것 같습니다.
우리의 개발자 문서도 자체적으로 개선되고 있습니다. 여기의 커밋 히스토리가 지금까지 노력이 어디에 집중되었는지를 가장 잘 보여줄 것입니다: Commits · discourse/discourse-developer-docs · GitHub
API 문서는 불완전하다고 할 수 있지만, 이 부분에서 우리의 스토리를 명확히 하기 위해 할 일이 많습니다. 과거에는 “API를 역공학(reverse engineer)하라”고 안내했지만, 그건 좋은 스토리가 아니라는 데 동의합니다. 자기 책임 하에 해킹(hacking)하는 용도라면 괜찮지만, 거기에 나열되지 않은 엔드포인트들은 의존하지 않는 것이 더 나은 경우가 있을 수 있습니다.
서버 측 API는 주로 우리의 프론트엔드 애플리케이션이 소비(consume)하도록 설계되었습니다. 프론트엔드에서는 JavaScript API를 제공하며, 백엔드 변경 사항을 가려줄 수 있으므로 이를 소비하는 것이 더 나은 인터페이스가 될 수 있습니다: Using the JS API
그렇다면 우리의 백엔드 API에 대해 어떤 안정성 보장을 할 수 있을까요?
그건 그 API 문서들이 처리해야 할 책임이라고 생각합니다. 이상적으로는 그곳에 문서화된 것이 우리가 지원하는 모든 엔드포인트의 부분 집합이지만, 통합을 구축하려는 타인을 위해 지원하려는 의도적인 부분 집합이어야 합니다. 반면, 거기에 나열되지 않은 것들은 의도적으로 문서화되지 않으며, 이는 오직 우리의 프론트엔드만을 위해 의도된 것들이므로 사전 통보 없이 변경될 수 있습니다.
이상적으로(제 생각에), 문서는 소스 코드에 내장되어 문서 자체가 테스트 대상이 되고, 플러그인으로 확장 가능하며, 앱 자체에서 제공되어 문서화된 인스턴스와 동기화되어야 합니다. 그렇게 하면 특정 사이트의 API 문서를 보고 해당 사이트가 실행 중인 버전의 문서를, 그리고 실제로 설치되고 활성화된 플러그인들을 볼 수 있게 됩니다.
저는 내부적으로 다른 사람들이 서버 측 API 스토리를 개선하기 위한 다른 아이디어들에 대해 많은 논의를 해왔다는 것을 알고 있습니다.
과거 몇 년간 개발자 경험(Developer Experience)에 있어 우리의 주요 초점은 프론트엔드 현대화에 있었기 때문에, 아직 이 영역에서 많은 우선순위를 두지 못했습니다.
그것이 언제 변할지 확신은 없지만, 서버 측 API 스토리를 꾸준히 개선해 나가기 위해 중간에 할 수 있는 작은 일들을 주시할 것입니다. 만약 구체적인 질문들이 제기된다면, 그걸 계기로 그 사이 더 집중적인 개선을 해나갈 수 있을 것입니다.
안정성 보장은 직관적인 API 버전 관리로 해결해야 합니다.
이 주제는 문서가 어디에 있는지, 즉 위치에 관한 것이 아니라 API가 어떻게 문서화되는지에 관한 것입니다. 부족한 것은 OpenAPI와 같은 표준화된 기계 가독 형식입니다.
이러한 부재와 버전 관리의 부재는 통합 작업을 마땅히 그래야 할 것보다 더 어렵고 취약하게 만듭니다. 문서화된 엔드포인트에 대한 기본적인 OpenAPI 스키마만 있어도 정말 도움이 될 것입니다.
본질적으로 이것은 문서화 문제가 아니라 구현 문제입니다.
@avdi 님이 몇 년 전에 이 문제를 제기했고, 데이터의 매개변수와 형식이 일관된 적절한 버전 관리가 된 JSON/REST API가 올바른 방향이라는 데 내부적으로 광범위한 합의가 이루어졌습니다.
현재 우리가 배포하는 API는 내부 API입니다. 100% 완전하고 포괄적이지만, 어색하고 형태가 자주 변합니다. 반환되는 형식과 엔드포인트는 모두 클라이언트 측 Ember 앱을 구동하는 데 최적화되어 있습니다. 몇 달이 지나면서 진화하고 형태가 변하므로, 핵심 업무에 의존하기가 어렵습니다. 이 API를 기반으로 구축하는 과정은 필요한 것보다 더 복잡합니다.
새로운 컨트롤러와 라우트 집합을 도입하면 여기서의 안정성 문제를 해결하고 REST API에 더 적합한 형식을 반환할 수 있게 됩니다. 예를 들어:
/api/v0/topic/1234.json 은 “일반적인 API 관행과 훨씬 더 일관된” 형식을 반환할 수 있습니다.
우리의 토픽 JSON에는 매우 복잡한 "Ember 클라이언트 전용 관심사"가 너무 많습니다:
timeline_lookup, post_stream, tags_descriptions 등… 등…
그럼에도 불구하고, 이 거대한 프로젝트를 시작하려면 로직이 중복되지 않도록 내부 재설계가 많이 필요합니다. 또한 플러그인들은 많은 내부 동작을 재구성하므로 API에 반영되어야 하며, 이로 인해 상황이 더 복잡해집니다. (assign이 이러한 형식에 어떤 영향을 미치는가?)
저는 우리가 이 모험에 나설 것이라고 확실히 보지만, 가까운 미래에는 아닐 것입니다.
변화에 시간이 걸리는 것은 충분히 합리적이라고 생각합니다. 저는 이전 회사에서 개발자 관계(Developer Relations)를 담당했는데, 정말… API를 개선된 상태로 만드는 데 2년이 넘게 걸렸습니다. 고려해야 할 복잡한 요소가 너무 많았고 (엔지니어링 팀은 변경할 수 없는 안정적인 엔드포인트를 만드는 아이디어를 싫어했습니다!)
그럼에도 불구하고, 더 작은 변화들은 시간이 지남에 따라, 그리고 더 짧은 시간 안에 이루어질 수 있다고 생각합니다. 솔직히 말해, 여러분이 라우트(또는 Ruby에서 라우트)를 어떻게 정의하는지 살펴본 적은 없지만, 쉽게 해결할 수 있는 간단한 사항들이 꽤 있을 거라고 추정합니다. 예를 들어:
모든 사람을 대신해 말할 수는 없지만, 현재 API 명세에 엔드포인트가 존재한다는 것만으로도—설계나 예시가 없더라도, 응답 모델이 유동적이어도—큰 성과가 될 것 같습니다. 때로는 어떤 것이 존재하는지 아는 것만으로도 절반의 싸움을 이기는 것과 같습니다.
API 문서가 OpenAPI 형식인가요?
https://docs.discourse.org/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Discourse API Documentation",
"x-logo": {
"url": "https://docs.discourse.org/logo.svg"
},
"version": "latest",
...
부끄럽게도, 나는 그걸 한 번도 눈치채지 못했네요…
이 점을 지적해 주셔서 감사합니다, @blake.