모든 API 엔드포인트에 대한 완전한 문서가 존재하지 않는 이유가 이해되지 않습니다. 원래 문서는 2014년 12월에 공개되었는데, 6년이 지난 지금도 문서는 여전히 미완성 상태입니다.
왜 이런 일이 일어나는 것일까요? 양질의 문서가 부재하고 API를 역설계하라는 제안은 API를 사용하려는 개발자들에게 상당한 장벽이 됩니다.
감사합니다.
좌절된 개발자
어떤 부분이 어렵거나 부족한지 몇 가지 예시를 들어 주실 수 있나요?
이 주제는 제 포럼에 경고가 표시되어 있어서 시의적절합니다. "비추천 인증 방식으로 API 요청을 감지했습니다."라는 경고입니다.
현재 사용해야 하는 인증 방식이 무엇인지, 그리고 포럼 관리자 입장에서 이를 구현하는 방법을 단계별로 알려주는 가이드를 알고 싶습니다.
제가 찾은 것은 오래된 스레드들이며, 그 안에는 GitHub 링크만 있고, 기술에 익숙하지 않은 저에게는 코드 참조가 도움이 되지 않습니다. 누군가 쉬운 말로 설명해 주실 수 있을까요?
올바른 API 인증은 문서의 맨 위에 나와 있습니다. 간단히 말해, URL 파라미터 대신 HTTP 헤더를 사용하여 API 키와 사용자 이름을 제공해야 합니다.
@justin 제 구체적인 사례는 Discourse API의 Python 래퍼를 서서히 배포하는 작업인데, 적절한 문서화가 부족한 점이 정말 버겁습니다. 이미 모든 엔드포인트를 수동으로 테스트해야 하는데, 그중 많은 엔드포인트가 아예 문서화되어 있지 않거나 잘못 문서화되어 있습니다.
문서 상단에는 API가 완전히 문서화되지 않았다고 명시되어 있습니다. 그 이유를 알고 싶습니다.
Reverse engineer the Discourse API 을 참조하세요.
해변의 모래알 하나하나가 왜 “완전히 문서화”되어 있지 않나요? 
궁금한 건, 왜 필요한 것만 지원하다가 새로운 미지원 요구사항에 부딪히면 그때 가서 역설계를 하지 않느냐는 겁니다. 100% 완성을 목표로 하는 것보다 훨씬 쉽고, 결국 쓰이지도 않을 호출을 감싸는 건 무의미하잖아요. 특히 지원 대상이 계속 변하는 상황에서 말이에요. 자기가 좀 더 편하게 하자는 겁니다.
이것이 역공학으로 분석될 수 있다는 점은 이해합니다. 하지만 이렇게 해야 한다는 사실은 조금 답답합니다. 이 API는 그 작동 원리를 분명히 알고 있는 사람들이 만들었으니, 왜 다른 사람들이 정보를 얻을 수 있도록 문서로 남겨두지 않는 걸까요?
이것은 큰 요구가 아니라고 생각합니다. 좋은 문서화는 어떤 프로젝트에서든 필수적입니다.
지금의 계획은 이렇습니다. 현재 문서화된 모든 엔드포인트를 제 저장소의 develop 브랜치에 미러링해 두었고, 이제 역공학(reverse-engineering)을 시작해야 하는 단계까지 왔습니다.
이미 GitHub - discourse/discourse_api_docs: Discourse API Documentation · GitHub 프로젝트에 기여를 시작하고 있지만, 이렇게 확립된 프로젝트에서 왜 이런 작업이 필요한지 정말로 의문이 듭니다.
무엇이든 마찬가지이지만, 이는 자원과 우선순위 문제입니다. API 표면은 방대합니다. 기술적으로 보면 모든 것이 해당되며, 모든 것이 API를 통해 접근되므로 리버스 엔지니어링이 가능한 것입니다. 우리는 제한적인 엔지니어링 시간을 문서화보다는 수정, 기능 추가, 성능 개선 등에 집중하는 것을 선택했습니다.我们的产品 방향은 주로 고객과 커뮤니티에 의해 주도됩니다. 제 지식 범위 내에서는 100% API 문서화를 요구한 고객이 한 번도 없었습니다. 고객이 누락되거나 명확하지 않은 사항에 대해 질문할 경우, 우리는 해당 내용을 추가합니다. 따라서 100% 커버리지는 우선순위가 아니었습니다.
현재 API 문서는 수동으로 관리되고 있습니다. 이는 분명히 지속 가능한 방법이 아니지만, 현재로서는 우리가 가진 방법입니다. API 문서 시스템을 프로그래매틱하게 생성되도록 리팩토링하는 것은 “할 일” 목록에 있지만, 현재 특정 릴리스에 계획되어 있지 않아 완료 시한이 없습니다.