<div id="readability-page-1" class="page"><div>
 자극적인 제목으로 어그로를 끌어봤다. 그렇지만 이 제목은 내 감정에 비하면 새 발의 피다. 작년과 올해 일을 하면서 API 문서에 대해서 많이 생각을 하게 되었다. 많은 업체들과 일하면서 API 문서를 받아서 작업을 할 경우도, 때로는 내가 만들어서 전달해 주어야 하는 경우가 있었다. API 문서 없음은 받은 경우에 해당한다.
내가 생각하는 그리고 경험이 좋았던 API 문서들은 대체적으로 클라우드 서비스를 하거나 IT서비스를 전문적으로 하는 경우가 많았던 것 같다. 그들의 문서들은 공통적으로 특징이 있었다. 
<ul>
<li>거의 80%이상 문서대로 구현하면 구현이 된다.</li>
<li>적절한 예시가 있다.</li>
<li>항상 최신화가 되어 있다.</li>
</ul>
대체적으로 최신화가 되어 있다는 것은 웹사이트 형태로 API 문서를 제공하는 경우가 많았고, PDF나 docx 형태여도 최신문서를 제대로 전달해 주는 곳들은 항상 연동 경험이 좋았다. 그리고 너무나도 당연하게 작업하는 입장에서 거칠게 없었고, 산정한 일정대로 일이 잘 진행되었다. 
경험이 좋지 않았던 API 문서는 당연히 위의 특징들과 반대였다. 
<ul>
<li>문서대로 구현이 되지 않는다.</li>
<li>적절한 예시는 없다. 설상 있더라도 동작되지 않는다.</li>
<li>웹사이트의 형태가 아니였고, 최신 문서를 전달해주지 못한다.</li>
</ul>
하나씩 곱씹어보면, 문서대로 구현이 되지 않는다. 라는게 가장 크게 불편한 경험이었다. 이유도 다양하다. 적혀있는 host, ip가 다른경우, 실제 문서에 있는 case sensitive 가 맞지 않는 경우, 특정 암호화나 복호화 관련된 부분이 있으면 실제 그것을 구성하는 구성요소들이 문서와 맞지 않았다. 문서대로 구현이 되지 않는다. 의 가장 큰 문제는 내가 처음 API 문서를 보고 계획했던 일정대로 되지 않는다는 것이다. 구현이 제대로 되지 않고, API통신이 제대로 되지 않으면 해당 업체 담당자에게 물어봐야 하고 그건 내가 (연동해야하는 API X API 내 예외 상황들의 수)만큼 비례해서 커뮤니케이션 비용이 커지는 상황들이 발생했다. 그리고 이 문제는 연동을 해봐야만 알 수가 있다. 
<code>적절한 예시가 없는 것</code>도 문제이다. 물론 필수는 아니지만, 해당 업체 입장에서도 다른 업체 사람이 계속 메일, 전화, 카카오톡을 할 정도고 그런 리소스가 계속 낭비가 될 텐데 예시 코드만 만들면 되는 것을 안 만들어서 계속 핑퐁이 오고 가게 하는 건 사실 이해하기가 힘들었다. 
최신 문서를 전달해 주지 못하는 건 업체의 사정일 수도 있겠지만 황당했던 건 해당 업체의 어떤 분은 주고 어떤 분은 주지 않는다는 것이었다. 그래서 두 개를 받아서 비교해서 생각하고 예상하는(?) 시간들도 있었던 것 같다. 
이제와서 드는 생각은 
왜 그렇게 큰 업체에서 API 문서를 제대로 만들고 관리하지 못할까?
스타트업이나 작은 업체라면 생존의 기로에서 API 문서는 사치일 수도 있겠다 싶다. 그런데 엄청 크고 상장까지 되어있는 회사들이 그런 경우를 보면, 몇 가지 생각이 들었다. 
<ul>
<li>처음에는 분명히 제대로 된 버전이 있었겠지.</li>
<li>회사가 커지고 커스터마이징이 생기면서 최신화도 어려웠을 것이고, 제대로 버전관리도 안되었을 것이고.</li>
<li>더 오래 되어서 들고 나는 사람들이 많아지면 관리가 안되었을 것이고</li>
<li>그래서 이렇게 되었겠지… 라는 생각.</li>
</ul>
예전에 다녔던 회사의 사례는 이랬다. API문서는 잘 되어있고, 예시코드도 잘 만들어져 있었다. 그런데 어느순간부터 어떤 문서가 최신문서인지 아는 사람이 아무도 없었다. SVN에 있는게 최신이 아니라는 이야기도 있었고, 특정 서버 안에 있는 문서가 최신이라는 이야기도 있었다. 그러다 보니 전달할 때 그냥 제일 최신에 수정된 파일의 날짜를 보고 전달을 했다. 당연히 최신문서는 아니였다. 
큰 회사라고 못하는 거라도 생각하지는 않는다. 실제로 좋은 경험을 주었던 업체들은 국내에서 제일 큰 업체도 있었고 작은 업체도 있었다. 
그 회사가, 그 회사의 기술 담당자, 기술 의사 결정권자들이 이 부분에 대해서 얼마나 진심이냐의 차이가 아닐까? 
내가 올해 드렸던 API 문서들도 이런 사례를 겪으면서 많은 부분 반영을 했다. 기존의 엑셀에서 노션(Notion) 기반으로 오픈API는 아니기 때문에 해당 업체 담당자분들을 초대/공유하는 식으로 변경을 해서 항상 최신문서를 바라보게 했다. API 문서에서 서두에 각 API를 소개하기 전에 인증(Authorization)이나 공통코드/응답형식을 정의하는 부분을 추가해서 API 연동시 필수적으로 만들어야 하는 부분을 먼저 만들 수 있도록 구성했다. 호출을 위한 예제 코드와 curl 을 통해서 실제 어떻게 API가 호출되는지를 예시로 넣었다. 그리고 암호화나 해시화에 대한 부분은 생성하는 파이썬 코드를 직접 넣었다. 
API 문서를 다듬으면서 그런 생각이 들었다. 이 문서를 보는 사람이 이 문서를 보고 개발을 할 때 좋은 경험을 느꼈으면 좋겠다고. 그리고 더 나아가서는 내가 일하는 회사에 대해서 좋은 감정을 가지면 좋겠다고. 내가 다른 회사의 좋은 API문서를 보면서 느꼈던 그 감정을 다른 개발자도 느꼈으면 좋겠다고 생각했다. 
규모나 경제의 문제가 아니라 마음의 문제가 아닐까 싶다.

 </div></div>

ASH84

ash84

자극적인 제목으로 어그로를 끌어봤다. 그렇지만 이 제목은 내 감정에 비하면 새 발의 피다. 작년과 올해 일을 하면서 API 문서에 대해서 많이 생각을 하게 되었다. 많은 업체들과 일하면서 API 문서를 받아서 작업을 할 경우도, 때로는 내가 만들어서 전달해 주어야 하는 경우가 있었다. API 문서 없음은 받은 경우에 해당한다.
내가 생각하는 그리고 경험이 좋았던 API 문서들은 대체적으로 클라우드 서비스를 하거나 IT서비스를 전문적으로 하는 경우가 많았던 것 같다. 그들의 문서들은 공통적으로 특징이 있었다. 
거의 80%이상 문서대로 구현하면 구현이 된다.
적절한 예시가 있다.
항상 최신화가 되어 있다.
대체적으로 최신화가 되어 있다는 것은 웹사이트 형태로 API 문서를 제공하는 경우가 많았고, PDF나 docx 형태여도 최신문서를 제대로 전달해 주는 곳들은 항상 연동 경험이 좋았다. 그리고 너무나도 당연하게 작업하는 입장에서 거칠게 없었고, 산정한 일정대로 일이 잘 진행되었다. 
경험이 좋지 않았던 API 문서는 당연히 위의 특징들과 반대였다. 
문서대로 구현이 되지 않는다.
적절한 예시는 없다. 설상 있더라도 동작되지 않는다.
웹사이트의 형태가 아니였고, 최신 문서를 전달해주지 못한다.
하나씩 곱씹어보면, 문서대로 구현이 되지 않는다. 라는게 가장 크게 불편한 경험이었다. 이유도 다양하다. 적혀있는 host, ip가 다른경우, 실제 문서에 있는 case sensitive 가 맞지 않는 경우, 특정 암호화나 복호화 관련된 부분이 있으면 실제 그것을 구성하는 구성요소들이 문서와 맞지 않았다. 문서대로 구현이 되지 않는다. 의 가장 큰 문제는 내가 처음 API 문서를 보고 계획했던 일정대로 되지 않는다는 것이다. 구현이 제대로 되지 않고, API통신이 제대로 되지 않으면 해당 업체 담당자에게 물어봐야 하고 그건 내가 (연동해야하는 API X API 내 예외 상황들의 수)만큼 비례해서 커뮤니케이션 비용이 커지는 상황들이 발생했다. 그리고 이 문제는 연동을 해봐야만 알 수가 있다. 
적절한 예시가 없는 것도 문제이다. 물론 필수는 아니지만, 해당 업체 입장에서도 다른 업체 사람이 계속 메일, 전화, 카카오톡을 할 정도고 그런 리소스가 계속 낭비가 될 텐데 예시 코드만 만들면 되는 것을 안 만들어서 계속 핑퐁이 오고 가게 하는 건 사실 이해하기가 힘들었다. 
최신 문서를 전달해 주지 못하는 건 업체의 사정일 수도 있겠지만 황당했던 건 해당 업체의 어떤 분은 주고 어떤 분은 주지 않는다는 것이었다. 그래서 두 개를 받아서 비교해서 생각하고 예상하는(?) 시간들도 있었던 것 같다. 
이제와서 드는 생각은 
왜 그렇게 큰 업체에서 API 문서를 제대로 만들고 관리하지 못할까?
스타트업이나 작은 업체라면 생존의 기로에서 API 문서는 사치일 수도 있겠다 싶다. 그런데 엄청 크고 상장까지 되어있는 회사들이 그런 경우를 보면, 몇 가지 생각이 들었다. 
처음에는 분명히 제대로 된 버전이 있었겠지.
회사가 커지고 커스터마이징이 생기면서 최신화도 어려웠을 것이고, 제대로 버전관리도 안되었을 것이고.
더 오래 되어서 들고 나는 사람들이 많아지면 관리가 안되었을 것이고
그래서 이렇게 되었겠지… 라는 생각.
예전에 다녔던 회사의 사례는 이랬다. API문서는 잘 되어있고, 예시코드도 잘 만들어져 있었다. 그런데 어느순간부터 어떤 문서가 최신문서인지 아는 사람이 아무도 없었다. SVN에 있는게 최신이 아니라는 이야기도 있었고, 특정 서버 안에 있는 문서가 최신이라는 이야기도 있었다. 그러다 보니 전달할 때 그냥 제일 최신에 수정된 파일의 날짜를 보고 전달을 했다. 당연히 최신문서는 아니였다. 
큰 회사라고 못하는 거라도 생각하지는 않는다. 실제로 좋은 경험을 주었던 업체들은 국내에서 제일 큰 업체도 있었고 작은 업체도 있었다. 
그 회사가, 그 회사의 기술 담당자, 기술 의사 결정권자들이 이 부분에 대해서 얼마나 진심이냐의 차이가 아닐까? 
내가 올해 드렸던 API 문서들도 이런 사례를 겪으면서 많은 부분 반영을 했다. 기존의 엑셀에서 노션(Notion) 기반으로 오픈API는 아니기 때문에 해당 업체 담당자분들을 초대/공유하는 식으로 변경을 해서 항상 최신문서를 바라보게 했다. API 문서에서 서두에 각 API를 소개하기 전에 인증(Authorization)이나 공통코드/응답형식을 정의하는 부분을 추가해서 API 연동시 필수적으로 만들어야 하는 부분을 먼저 만들 수 있도록 구성했다. 호출을 위한 예제 코드와 curl 을 통해서 실제 어떻게 API가 호출되는지를 예시로 넣었다. 그리고 암호화나 해시화에 대한 부분은 생성하는 파이썬 코드를 직접 넣었다. 
API 문서를 다듬으면서 그런 생각이 들었다. 이 문서를 보는 사람이 이 문서를 보고 개발을 할 때 좋은 경험을 느꼈으면 좋겠다고. 그리고 더 나아가서는 내가 일하는 회사에 대해서 좋은 감정을 가지면 좋겠다고. 내가 다른 회사의 좋은 API문서를 보면서 느꼈던 그 감정을 다른 개발자도 느꼈으면 좋겠다고 생각했다. 
규모나 경제의 문제가 아니라 마음의 문제가 아닐까 싶다.

API 문서 없음.

댓글