초보 기획자/PM을 위한 API 보는 법 (1)
초보 기획자/PM은 딱 이만큼만 알아도 됩니다
API를 처음 맞닥뜨리는 순간
처음 서비스 기획 또는 프로젝트 매니징을 하게 되면 가장 먼저 맞닥뜨리는 곤혹스러운 부분 중 하나가 바로 API가 아닌가 싶다.
특히나 고객 또는 대표님의 갖가지 다양한 (그리고 수시로 바뀌는) 요구사항을 정리하고, 이를 와이어프레임과 IA 문서 등으로 최종적으로 정리하여 "후, 이쯤 되면 내 역할은 이제 다 된 거겠지?" 싶은 순간, 그래서 이제 기획은 끝났으니 검토 후 디자이너, 개발자분들이 알아서 척척 만들어주면 될 것 같은 순간에 API는 찾아온다.
그리고 이는 아마도 아래의 모습으로 찾아올 것이다.
- 백엔드 개발자분이 API는 우선 다 짜 놨다고 한다. 근데 그게 뭐지? 내가 뭐 어쩌면 되는 거지?
- 프런트 개발자분이 API가 다르다고 한다. 조율을 해 드려야 할 것 같은데 그게 뭐지? 그리고 뭐가 다른 거지?
- 기존 서비스에서 비슷한 게 있는 것 같아서 물어봤더니 API를 새로 짜야한단다. 그게 뭐지? 왜지...?
- 그건 우리 API가 아니란다. 그래서 계약을 하거나, 나중에 문제가 생길 수도 있단다. 그게 뭐지? 왜지...?
- 기타 등등
적어도 이런 뜻은 아닐 거다이미 시중의 여러 아티클이나 강의 자료에서는, JSON 형식에 대한 설명이나 클라이언트와 서버의 소통 등을 도식화하여 API에 대한 기술 내지는 절차적 개요에 대해 설명한다.
그런데 대체 무슨 맥락에서 API가 초보 기획자/PM에게 문제가 되고, 그리고 그 상황에서 API를 뭘 어떻게 들여다보면 되는지에 대한 설명은 다소 부족한 듯싶어, 이 부분에 대해, 여러 조직 혹은 팀에서 사용하고 있을 API 문서화 툴인 SWAGGER와 함께 설명하고자 한다.
※ 단, 쉽게 설명하는 만큼 개념의 엄밀함, 기술적 이야기 등은 대부분 배제하였다
1. 서비스는 결국 정보를 생성, 수정, 조회, 삭제하는 활동이다. 이걸 API가 해준다.
기획자 혹은 PM으로써 개발 관련 영상이나 강의를 찾다 보면 CRUD, 라는 이야기를 들어보게 된다. 이런저런 배경 설명 등이 붙는데, 쉽게 요약하면 우리가 기획하는 웹이나 앱은, 결국 사용자가 특정 활동을 통해 정보를 생성Create하고, 조회Read하고, 수정 및 업데이트Update하고, 삭제Delete한다는 이야기다.
그리고 이렇게 변경되는 모든 정보는 사용자가 바라보는 화면인 프론트엔드/클라이언트와 백엔드/서버 사이에서 오고 간다. 사용자가 변경한 정보가 서버로 넘어가고, 서버에 있는 정보가 다시 사용자에게 전달된다.
결국 심플하게 모든 서비스는 사용자가 생성, 수정, 삭제한 정보가 서버에 반영되고 이 결과를 다시 사용자에게 보여주는 식이다. 그리고 그 창구가 API다.
엄밀한 설명은 아니지만, 초보 기획자/pm에게 필요한 만큼만 퉁치면 위와 같다.가령 브런치의 [내 브런치] 메뉴를 위의 관점에서 바라보자. [내 브런치]에는 크게 아래의 기능이 제공된다.
1. 프로필을 보여준다(조회한다)
2. 유형/탭 별 게시글 목록을 불러온다 + 선택하면 해당 게시글의 상세 내용을 조회할 수 있다
3. 광고 배너를 보여준다(조회한다)
(4. 글쓰기, 제안하기, 메뉴 등도 있는데 우선 설명에선 제외한다).
그럼 이를 API의 관점에서 생각해보면
1. 서버에 있는 나의 프로필 정보를 가져와서 조회Read 할 수 있게 해주는 API
2. 서버에 있는 광고 베너 정보를 가져와서 조회Read 할 수 있게 해주는 API
3. 서버에 있는 나의 유형별 게시글 목록을 가져와서 조회Read 할 수 있게 해주는 API
4. 서버에 있는 나의 게시글 상세 내용을 가져와서 조회Read 할 수 있게 해주는 API
가 필요할 것이다.
2. 메소드? (feat. SWAGGER)
이렇게 생성, 조회, 수정, 삭제를 위해서는 API가 필요하다. 그런데 이를 하나의 API가 모두 퉁쳐서 해주는 건 아니다. 생성을 위한 API와 수정을 위한 API, 삭제를 위한 API, 조회를 위한 API가 별개다.
다만 여기엔 메소드(Method) 관련 설명이 붙으면서, 위에서 이야기한 CRUD와는 말로 표현된다. 그러나 초보 기획자/PM이 알아야 하는 차원에선 사실상 같다.
- GET 메소드 : 정보를 조회Read 하게 해주는 API
- POST 메소드 : 정보를 생성Create 하게 해주는 API
- PUT, PATCH 메소드 : 정보를 수정 및 업데이트Update 하게 해주는API
- DELETE 메소드: 정보를 삭제Delete 하게 해주는 API
실제로 SWAGGER 등 API를 문서화해둔 걸 살펴보면 Create, Read, Update, Delete가 아닌 위의 메소드로 구분되어있는 걸 확인할 수 있다. 구체적으로 무슨 정보를 어떤 형식으로 가져오는지는 모르지만, 일단 정보를 생성하기 위한 API인지, 혹은 수정하거나 삭제하기 위한 API인지는 메소드를 통해 알 수 있다.
3. 오픈 API?
그런데, 이런 API는 모두 우리 회사, 조직 내에서만 알아서 만드는 걸까? API는 정보를 불러오는 용도이기도 한데, 모든 정보는 우리 회사 내에 있는 걸까? 당연히 아니다.
- 불가능 : 모든 정보를 우리 회사, 조직이 알아서 만들어서 불러올 수 없다
- 불필요 : 우리 회사, 조직이 기술적으로 할 수 있더라도 굳이 그럴 필요가 없을 수도 있다
가령, 구글의 지도 정보가 필요한데 우리가 이를 모두 만들 수나 있을까? 혹은 전국의 학교 정보가 필요한데, 열심히 발품 팔면 만드는 건 가능하지만, 굳이 우리가 이를 직접 해야 할까? 그리고 많은 경우, 이미 이런 정보와 API를 누군가가 무료로 제공하고 있다. 이를 오픈 API라고 부른다.
아래는 여러 기관, 단체에서 제공하는 Open API의 사례이다. Open API는 모두 개요, 사용법, 불러올 수 있는 정보에 대한 설명을 포함하고 있고, 간단한 신청, 허가 방식으로 사용 권한을 제공받는다.
4. 정리하면...
결국 정리하면
1. 모든 서비스는 사용자가 정보를 생성, 수정, 삭제, 조회하는 서비스인데
2. 사용자와 서버 사이에 이렇게 정보가 오고 가려면 API가 필요하고
3. 이를 GET, POST, PUT/PATCH, DELTE 유형으로 분류할 수 있고
4. 이걸 꼭 팀/조직 내에서 만들어 쓰는 대신, 공용으로 제공되는 Open API라는 걸 이용할 수도 있다
결국 API라는 걸 쉽게 분류해보면 위와 같다. CRUD 관점에서의 4가지 유형과 우리 것, 남의 것.이어지는 글에서는
- 프로젝트 시 구체적으로 API에 관해 소통이 발생하는 사례와
- 이를 조율, 확인하기 위해 API를 보는 법
에 관해 정리하고자 한다.
