Splitting Your Data & Application APIs: Going Further

요약: API를 데이터와 애플리케이션 API로 분리하는 것을 고려하고 있다면, 여기서 제안하는 대로 애플리케이션 API를 JSON에서 하이퍼미디어(HTML)로 변경하고 htmx와 같은 하이퍼미디어 지향 라이브러리를 사용하여서 하이퍼미디어 모델의 장점(단순성, 신뢰성, 유연성 등)을 누릴 수 있습니다.

#문제점

최근 Max Chernyak이 “자신의 프론트엔드를 위한 범용 API를 만들지 마세요“라는 제목의 에세이를 작성했습니다. 그의 요약은 다음과 같습니다:

YAGNI(You Ain’t Gonna Need It, 필요하지 않다는 의미)는 대기업의 연합 프론트엔드나 GraphQL을 사용하는 경우를 제외하고는 적용됩니다.

Max는 범용 API와 애플리케이션 API의 다양한 요구 사항을 설명하며, 다음과 같은 범용 API의 필요성을 나열합니다:

그리고 애플리케이션 API의 필요성으로는 다음을 언급합니다:

저는 이 문제를 데이터/애플리케이션 API 불일치 문제라고 부르겠습니다.

Max의 제안은 API를 범용 API와 애플리케이션 API의 두 “반쪽“으로 분리하는 것입니다:

프론트엔드를 범용 API 클라이언트로 취급하는 것을 중단하고, 애플리케이션의 한 부분으로 취급하기 시작하세요.

“페이지” 전체의 JSON을 전송할 수 있다고 상상해 보세요. /page/a라는 엔드포인트를 만들어 /page/a에 대한 전체 JSON을 렌더링하세요. 모든 페이지에 대해 이렇게 하세요. 프론트엔드 개발자에게 복잡한 페이지를 렌더링하기 위해 여러 개의 개별 요청을 보내도록 강요하지 마세요. 인위적인 제한으로 그들을 괴롭히지 마세요. 협력하세요.

#문제를 정확히 지적함

Max가 제기한 문제에 전적으로 동의합니다.

특히 범용 API는 안정적이어야 하는 반면, 애플리케이션 API는 애플리케이션의 필요에 맞게 빠르게 변경되어야 한다는 점을 강조하고 싶습니다.

Jean-Jacques Dubray는 이 기사에서 API 설계자들에게 다음과 같은 상황을 설명합니다:

요즘 내 일의 가장 힘든 부분은 프론트엔드 개발자를 위한 API를 설계하는 것입니다. 대화는 항상 이렇게 진행됩니다:

Dev – 그래서 이 화면에는 데이터 요소 x, y, z가 필요합니다… {x:, y:, z:} 형식의 응답을 반환하는 API를 만들어 주실 수 있나요?

Me – 알겠습니다

이것은 Max가 언급한 긴장감을 완벽하게 encapsulation한 예입니다. API 엔지니어들은 일반적이고 안정적인 API를 설계하고 싶어하지만, 자주 변경되는 UI와 서버 측에서 최적으로 해결되는 복잡한 데이터 요구 사항에 종속됩니다.

Max가 지적했듯이:

“페이지 a“를 단순하게 유지하여 필요한 작업만 수행하도록 하세요. “페이지 a“에 대한 버그, 보안, 성능을 철저히 테스트하세요. 심지어 “페이지 a“에 필요한 모든 것을 하나의 큰 SQL 쿼리로 가져올 수 있습니다.

#해결책에 대한 부족함

다시 말해, Max가 제기한 데이터/애플리케이션 API 불일치 문제에 전적으로 동의하며, API를 둘로 나누자는 그의 제안을 칭찬합니다.

하지만, 여기에는 다음 단계가 있습니다:

애플리케이션 API를 범용 데이터 API와 분리한 후에는, 공개 데이터 API의 제약에 얽매이지 않고 애플리케이션 API의 전체 형태를 재고할 수 있습니다. 자유롭게 생각을 확장할 수 있는 기회가 생깁니다.

애플리케이션 API의 핵심 문제는 빠른 변화와 페이지(또는 리소스)별 조정입니다. 우리는 정확히 이 문제를 다루기 위한 매우 훌륭한 기술을 가지고 있습니다: 하이퍼미디어입니다!

하이퍼미디어는 HATEOAS를 통해 API 변화가 문제가 되지 않게 만듭니다. 하이퍼미디어 API의 형태가 변경되면, 그것은 새로운 HTML로 반영됩니다. 새로운 API는 브라우저와 같은 클라이언트를 업데이트할 필요 없이 단순히 서버에서 반환되는 새로운 HTML로 나타납니다.

브라우저는 새로운 HTML을 보고, 이를 사용하는 사람들은 새로운 기능에 적절히 반응합니다.

따라서, Max가 옳은 방향으로 가고 있다고 생각하지만, 그는 충분히 멀리 가지 않았습니다: 데이터/애플리케이션 API 불일치 문제를 해결하기 위해 API를 분리하는 정신적 도약을 했다면, 하이퍼미디어의 장점을 재발견하는 것은 그 길에서 한 걸음 더 나아가는 것입니다.

“하지만 하이퍼미디어 애플리케이션은 사용성이 떨어지기 때문에 웹 1.0으로 돌아가고 싶지 않다“고 반대할 수도 있습니다.

그것은 매우 합리적인 반대 의견이지만, 사람들은 그 문제를 해결하기 위해 노력해 왔고, 이제 HTML의 사용성 문제를 해결하는 여러 라이브러리가 있습니다.

제가 좋아하는 두 가지는 unpoly와, 물론 제가 만든 htmx입니다.

#결론

하이퍼미디어 애플리케이션 API(즉, “HTML을 사용하세요, 예전처럼”)로 전환하면 REST-ful 웹 모델의 모든 이점(단순성, 신뢰성 등)과 성숙한 웹 프레임워크에서 서버 측 렌더링의 이점(캐싱, SQL 튜닝 등)을 누릴 수 있습니다.

그리고 htmx와 같은 하이퍼미디어 지향 프론트엔드 기술을 선택함으로써 그 모델 내에서 탁월한 사용자 경험을 만들 수 있습니다.

모든 것은 다시 새로워지지만, 이번에는 조금 더 나아졌습니다.