Code Metaphor

Me2PHP를 공개한지 거의 2년이 다 됐다. 사실 작년 중순까지만 해도 API 명세가 바뀌면 최대한 빠르게 반영해왔고, 그런 점 때문에 많은 분들이 Me2PHP를 사용해 주셨다.¹ 하지만 너무 자주 바뀌는 API 명세에 맞게 유지하기는 점점 힘들어졌고, 근 반 년 정도는 Me2PHP에 손을 놓은 상태였다. 워낙 많은 분들이 Me2PHP를 사용하고 있는 상황이라 애초 마음과 달리 재미가 아닌 의무감에 의한 유지를, 치명적인 버그가 발생했을 때만, 조금씩 해왔을 뿐이다. 그나마도 모든 치명적인 버그를 다 해결한 것도 아니었다.

여담으로, 이참에 미투데이 API의 명세 업데이트에 관한 중요한 문제점을 하나 지적하고 넘어가자. 기본적으로 미투데이의 명세 업데이트는 최대한 하위호환성을 염두하는 듯하다. 하지만 이 하위호환성은 “에러가 나지 않을 정도”의 호환성이지, “버그가 나지 않을 정도”의 호환성을 뜻하지는 않는다. 예를 들어 제공하던 애트리뷰트를 빼려고 하는데, 아예 제거하면 오류가 날 수도 있으니 공백 문자열을 넣어주는 식이다. 난 이런 어중간한 친절함이 항상 좋다고 보진 않는다. 오히려 에러가 났다면 빨리 발견할 수 있는 버그를 오랫동안 남게 만들 수도 있다.

Me2PHP 같은 경우 더 큰 문제가 생긴다. Me2PHP는 객체 모델 맵핑을 하는 디자인이고, 예를 들어 포스팅을 가져오는데도 $person->getPosts(array('offset' => 0, 'limit' => 200, 'from' => '2009-01-01', 'to' => date('Y-m-d')))와 같은 형태를 쓰지 않고 반복자를 사용해 $person->posts->from('2009-01-01')->slice(0, 200)²과 같이 쿼리를 가능하게 한다. 하지만 백조가 헤엄치듯 클라이언트 코드에서만 예쁘고 내부 구현은 지저분하게 되어 있다. 예를 들어 미투데이 API가 예전에는 포스팅을 가져오는데 갯수 제한이 없었지만, 이제는 최대 100개만 가능하게 되었다. 그래서 200개를 가져온다거나, slice()를 생략하고 모든 포스팅을 가져오려고 하면, 내부적으로는 100개씩 가져오는 요청을 알아서 여러번 해야 한다. 최근 미투데이 API 명세가 업데이트되는 것들을 보면, 스트레스 문제 때문인지 이런 식으로 한 요청에서 가능한 범위를 줄이는 것들이 많이 있다. 당연히 Me2API는 기존의 행동을 유지하기 위해 더 지저분한 고려를 내부적으로 하게 된다.

하지만 정말 중요한 문제는 이것이 아니라, 모든 명세의 변경과 그 공지가 일방적이라는 데에 있다. 명세가 변경되면 문서가 바뀐 다음, MDN에 공지 글이 올라온다. 그리고 정말 중요한 변화인 경우 꽃띠앙 님의 미투데이에도 포스팅이 된다. 꼼꼼한, 혹은 나처럼 중간 라이브러리를 만들었기 때문에 의무감이 생긴 개발자라면 명세가 올라오는 스프링노트도 구독하고, MDN 메일도 꼬박꼬박 읽고, 꽃띠앙 님의 미투데이도 자주 확인하겠지만, 그렇지 않다면 업데이트 소식을 모를 수도 있다. 그렇다고 명세를 2년 전 그대로 유지해야 하나.

Me2PHP를 만들고 유지한 경험이 내게 큰 도움을 줬다고 생각한다. VLAAH의 API를 설계하는 데에 있어서. 애초에 VLAAH API는 설계할 때부터 프로토콜 버전을 자연스럽게 올릴 수 있도록 염두를 많이 했다. 클라이언트 라이브러리 개발자, 매시업 개발자로서 유지에 어떠한 고충이 있는지 꽤 많이 겪어본 뒤이기 때문에, 명세를 디자인하는데 이 부분의 우선 순위는 가장 높았다. VLAAH API가 선택한 방법은 HTTP의 내용 협상(content negotiation)과 같은 방식이다. VLAAH API에서는 그것을 프로토콜 협상(protocol negotiation)이라고 한다. 요청시 X-Accept-Protocol: 1.0; q=0.5, 0.9; q=1.0 헤더를 함께 보내면, 이것은 API 0.9를 우선으로 하되, 차선으로 API 1.0 형식도 괜찮다는 뜻이다. 만약 API 0.9가 여전히 지원되고 있다면, X-Protocol: 0.9와 같은 응답을 할 것이다. 그렇지만 API 0.9가 유지되고는 있으나 곧 사라질 운명이라면, X-Protocol: 0.9; expires=2009-12-25와 같은 응답을 하게 된다. 이미 API 0.9의 유지가 끝났다면, X-Protocol: 1.0으로 응답할 것이다. 요청 시에 X-Accept-Protocol 헤더를 보내지 않으면 그것은 X-Accept-Protocol: *; q=1.0과 같다. 항상 최신 버전의 포로토콜로 응답할 것이다.³

그리고 이러한 프로토콜 협상에 관한 사항은 API 문서의 맨 처음에 언급된다. 또한 직접 HTTP 요청 코드를 만드는 대신, 이미 있는 클라이언트 라이브러리를 쓰라고 권고한다. 클라이언트 라이브러리들에는 이미 버전 협상에 관한 것과, 협상에 실패했을 때의 예외 처리, 곧 파기될(deprecated) 프로토콜 버전에 관한 경고에 대해 잘 고려해서 작성되어 있기 때문이다. 현재 있는 클라이언트 라이브러리는 VLAAH-Ruby, vlaah-python 둘 뿐이지만, 모두 해당 부분에 관해 잘 고려되어 있다.

또 다른 문제가 하나 있다면, 회귀 테스트(regression test)가 불가능하다는 점이다. 가능한데 못 찾는게 아니라, 정말 불가능하다. 나는 그렇게 결론지었다. 이것은 꼭 미투데이 API만의 문제는 아니라고 생각한다. API에서 아예 샌드박스(sandbox)를 지원하기 전까지는 회귀 테스트는 요원하다. 그렇지 않으면 일시에 명세가 업데이트될 경우 테스트가 실패하도록 구성할 방법이 없다. 업데이트 공지를 발견하고 부랴부랴 가짜 응답 코드를 고쳐야 하기 때문이다. 아니면 API가 읽기 전용(read only)이여야 한다. 읽는 것만 가능하면(현재 VLAAH API가 그렇다) 그나마 테스트가 가능해진다. 예를 들어 sandbox라는 아이디로 계정을 만들어서 픽스쳐(fixture)를 구성할 수 있다. 하지만 데이터를 조작하는 API는 테스트하기 힘들다. 이를테면 포스팅하는 API를 테스트하고 그것을 삭제해야 하는데, 포스팅과 삭제가 동시에 잘 되는지 둘 다 작동하지 않는지는 가려내기 힘들다. 결정적으로 미투데이는 낙장불입이다. 한번 포스팅을 해버리면 픽스쳐가 영구히 변경된다;;;

여하튼 위와 같은 많은 고충들이 있어서, 결국 나는 손을 놓기로 결정했다! 대신 내 후배인 이흥섭이 프로젝트를 포크했다.

http://bitbucket.org/heungsub/me2pheungp/

프로젝트 이름이 Me2PHeungP랜다. 작명 진짜 구리다. 여하튼 이건 최근의 API 명세를 확실히 반영하고 있다. 앞으로는 이 라이브러리를 이용하길 권한다. 어차피 기존 Me2PHP를 포크했으므로 인터페이스는 동일하게 유지된다. 다만 내가 유지하는게 아니니 디자인이 약간 달라질 수도 있다. 그리고 가끔 나도 패치를 제공할 예정이다. 그러니까, 내 Me2PHP 리파지토리에는 이제 커밋이 되지 않을 예정이다.

주변에 Me2PHP를 쓰는 사람이 있다면 이 소식을 널리; 알려주시기 바란다.