아래 내용은 "What Is API Documentation?"이라는 기사 중 일부 내용을 정리한 글입니다.
기사는 intercom 2014 9월호에 실린 내용입니다.
저자는 Scot marvin 이며 아마존 웹서비스 API 문서 작성에 참여했고 좀 더 찾아보면 API 관련해서 인터뷰나 글을 찾을 수 있습니다.
http://scotmarvin.com/ 이란 개인 웹사이트가 있지만 요즘에는 주로 트위터에 글을 올리는 듯..
* 원본 기사는 아래 사이트에 보면 PDF와 연결된 링크가 있습니다. 드롭박스에 보관된 것이라 링크가 사라질지 몰라 관련 글만 소개합니다.
http://idratherbewriting.com/2014/09/10/stc-intercom-issue-entirely-dedicated-to-api-documentation/
사실 이 글을 읽으면서 프로그래밍 언어와 API 가 어떤 차이가 있는지 혼란스러웠습니다. 사람들이 한글과 한국어를 혼란스러워하는 것과 비슷하긴 합니다.
최근 논란이 되고 있는 오라클과 구글 간의 저작권 문제도 자바 언어 자체에 대한 이슈가 아니라 API 저작권에 대한 문제라는 설명을 보고 더 혼란스러웠거든요.
...이번 소송의 쟁점은 엄밀히 말해 자바 프로그래밍 언어가 아니다. 이 언어를 최적화한 API를 무단 도용했다는 것이 오라클의 주장이었다...
http://news.inews24.com/php/news_view.php?g_serial=820904&g_menu=020600&rrf=nv
API가 다양한 형식을 가지고 있지만 이 글에서 언급한 내용은 일단 요청/응답 구조로 되어 있는 API에 대해 설명하고 있습니다. 프로그래밍 언어에 포함된 API는 좀 더 복잡한 구조를 가지겠지만 일반적인 구조는 아래와 같다고 합니다.
- 문법적인 형식
- 사용 방법
- 기본값, 유효값, 데이터 타입
- 반환하는 값
- 에러 메시지 처리
- 요청/응답 처리 예제
그리고 API 문서만으로는 모든 사용자의 요구사항을 다 담을 수 없기 때문에 별도의 문서가 필요합니다. 일반적으로 개발자 가이드, 사용자 가이드, 초보자를 위한 가이드로 분류됩니다.
개발자 가이드는 실제 API를 사용할 때 필요한 예제, 유즈케이스를 담고 있고
사용자 가이드는 관련된 도구(툴)을 사용하는 방식이라든지 기타 부가적인 안내를 담고 있습니다.
초보자를 위한 가이드는 말 그대로 누구나 따라하기 식으로 배울 수 있는 가이드를 이야기합니다.
흥미로운 것은 API 문서를 개발자가 작성하는 것이 아니라 별도 담당자가 코드를 분석해서 작성한다는 겁니다. 물론 회사나 분야마다 차이가 있겠지만 아무래도 아마존 웹서비스는 사용자 층이 워낙 다양하다보니 일관성 있고 전문적인 가이드가 필요했기 때문이 아닌가 싶습니다.
그럼 API 문서를 작성하기 위해서는 어떤 자질이 있어야 하는지에 대해서도 설명해줍니다.
사실 자질보다는 이런 이런 것을 알아야 한다는 정도인듯 합니다.
- 코드
전문 개발자 수준은 아니더라도 코드를 읽고 이해할 수만 있으면 된다고 합니다. 이 코드가 왜 쓰여졌고 어떻게 동작하며 누가 어떤 상황에서 쓰게 되는지를 알아야 한다는 거죠.
음. 이 정도가 되려면 코드가 아주 깔끔하게 작성되거나 내공이 있는 개발자가 아니면 불가능할 것 같은데 하여간 그렇다고 합니다. 필요하면 전문서적을 참고하라는...
- API 기술
XML, JSON, REST, SOAP 같은 기술은 어느 정도 꿰고 있어야 한다는 거죠.
- 다양한 API 문서 참조
구글, 아마존, 트위터 등등 API 문서를 보면 일정한 스타일이 있기 때문에 참조하라는 겁니다. 예전에는 대부분 JavaDoc 스타일이었는데 최근에는 많이 바뀐 것 같습니다.
- 전문가에게 물어보기
아무래도 직접 코드를 개발한 전문가에게 어떤 의도로 이렇게 코드를 작성했는지 물어보는 것이 가장 확실하겠죠. 하지만 이런 경우에도 물어보기 전에 충분하게 준비를 해야 한다고 합니다.
Don't waste developer time because you didn't do your research first.
- 직접 해보기
코드나 개발자의 말만 믿지 말고 애매한 경우에는 직접 테스트를 해봐야 한다는...
좀 더 자세한 프로세스를 알고 싶지만 간단하게 소개만 하는 글이라서 충분한 내용이 담겨져 있지는 않습니다. 저자 입장에서는 이런 시장(API 문서 작성)이 점점 커져 가는데 인력이 부족하다고 하네요. 물론 영어권이겠지만... 시장이 커진다는 것은 나쁘지 않은 것 같습니다.
하지만 API 처럼 일정한 형식을 가지는 문서를 작성하는 것은 시장이 충분히 커지기 전에 로봇이 대체하지 않을까 하는 생각을 ~~
