본질적으로 이것은 문서화 문제가 아니라 구현 문제입니다.
@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이 이러한 형식에 어떤 영향을 미치는가?)
저는 우리가 이 모험에 나설 것이라고 확실히 보지만, 가까운 미래에는 아닐 것입니다.