초보 기획자/PM을 위한 API 보는 법 (2)
세부 사례, 근데 이제 SWAGGER를 곁들인
Previously...
1. 모든 서비스는 사용자가 정보를 생성, 수정, 삭제, 조회하는 서비스인데
2. 사용자와 서버 사이에 이렇게 정보가 오고 가려면 API가 필요하고
3. 이를 GET, POST, PUT/PATCH, DELTE 유형으로 분류할 수 있고
4. 이걸 꼭 팀/조직 내에서 만들어 쓰는 대신, 공용으로 제공되는 Open API라는 걸 이용할 수도 있다
이전 글에서는 초보 기획자가 알아야 할 API에 관한 설명을 했다면, 이번 글에서는 실제 기획, 프로젝트 단계에서 맞닥뜨리는 상황을 SWAGGER의 사례와 함께 살펴보고자 한다.
기획, 프로젝트 과정에서 기획자/PM이 API와 관련해서 맞닥뜨릴 질문은 사실 대부분 아래와 같을 것이다.
1) 이런 정보를 불러와야 하는데 그걸 불러올 api가 있나?
2) 뭐가 있긴 있는 것 같은데 구체적으로 어떤 값을 어떻게 불러오는 거지?
3) 약간 다른 거 같은데 이건 무조건 백엔드 개발자분이 해주셔야 하나?
이번 글에서는 위의 1), 2) 번에 관한 내용을 정리하고자 한다.
1. 이런 정보를 불러와야 하는데 그걸 불러올 API가 있나? ▶ 어떤 API가 있는지 확인해보자
팀에서 API 문서화 툴인 SWAGGER를 사용하고 있다면, 아래와 같이 팀에서 사용 중인 SWAGGER의 접근 권한을 제공받을 것이다. 해당 SWAGGER에 접근할 수 있는 경로와, 해당 SWAGGER의 이름 등이 나타나 있다.
접근 경로와 권한을 제공받아 처음 들어간 SWAGGER의 모습. 해당 SWAGGER의 주소와 이름 밑에 API 들을 확인할 수 있다.API는 주로 특정 기능 단위로 분류해둔다. 가령 제품이 크게 회원가입/로그인, 마이페이지, 커뮤니티 게시판 3가지로 구성된다면, API도 이와 마찬가지로 회원가입/로그인, 마이페이지, 커뮤니티 단위로 묶어 분류해놨을 것이다. 따라서 우선, 내가 확인하고자 하는 API가 어떤 제품/기능 단위에 속해있을지 먼저 찾아보자.
주로 주요 기능 단위로 분류되어 있다.그리고 API는 메소드(Method) 단위로 다시 분류될 수 있다. 이전 글에서도 설명했다시피, 서비스는 결국 사용자가 데이터를 생성Create, 조회Read, 수정Update, 그리고 삭제Delete하는 게 핵심이다. 그리고 API에서는 이를 메소드(Method)라는 개념을 더해 GET, POST, PUT, PATCH, DELETE 메소드의 API로 분류해놓는다. 관련된 API를 찾고 싶다면, 내가 기획하려는 기능이 사용자가 정보를 생성하는 기능인지, 조회하는 기능인지, 있는 것을 수정하는 기능인지, 혹은 삭제하는 기능인지를 생각해보자.
가령 브런치의 [프로필 편집]에 관한 부분을 응용하거나 리뉴얼 하고 싶어 관련된 API를 확인한다고 가정해보자.
- 회원정보에 관한 API는 모두 account라는 분류 하위에
- 저장해둔 회원 정보를 불러와 조회하는 GET 메소드의 API와
- 회원 정보를 입력/저장하는 POST 메소드의 API와
- 회원 정보를 수정/저장하는 PUT, PATCH 메소드의 API와
- 회원 정보를 삭제하는 DELETE 메소드의 API가 있을 것이다
다만 위의 메소드(Method)는 어디까지나 분류이므로, 특정 API를 의미하지는 않는다. 따라서 기능과 메소드로도 분류해서 찾았다면, 마지막으로 API의 이름을 들여다보면 내가 찾고자 하는 특정 API를 찾을 수 있을 것이다.
가령 [커뮤니티]라는 서비스/기능에서 사용자가 정보를 생성Create하는 부분에 관한 API를 찾고자 한다면
1) community라는 분류 하위에
2) POST 메소드(Method)로 표기된 API 중에 있을 것이다
다만 이런 API가 한글로 "커뮤니티 게시글 생성 API"라고 되어있진 않다. 흔히 보는 주소, 경로와 유사한 형태로 되어있는데, 겁 먹지는 말자. 자신이 API를 확인해보고자 하는 프로덕트에 대해 조금만 이해하고 있다면, 명칭을 조금만 들여다봐도 무엇에 관한 API일지 알아볼 수 있다.
※ 참고 : API의 설계, 명칭 규칙이라는 게 있는데, 초보 기획자/PM이 이를 굳이 신경 쓸 필요는 없다. 다만 이런 게 있구나, 저 이름이 맘대로 지어진 건 아니구나, 정도만 이해하면 된다.
2. API가 있긴 있는데, 그래서 무슨 정보가 오가는 걸까? ▶ API에 무슨 값을 넣으면 무슨 결과가 오는지 확인해보자
그럼 각 API에선 구체적으로 어떤 데이터 값이 오고 가는 걸까?
우선 API 사례를 살펴보기 전에, 브런치 [프로필 편집]의 일부 기능을 사례로 먼저 살펴보자. 아래 화면에서 사용자가 조회GET 할 수 있는 정보는 아래와 같다. 즉, 프로필 관련 GET 메소드의 API는 아래의 정보를 불러올 것이다.
- 저장해둔 프로필 이미지
- 작가명
- 직업
- 소개
- 작가 키워드
브런치 [프로필 편집]의 일부. 프로필 정보를 불러오는 GET 메소드 API라면 프로필 이미지, 작가명, 직업, 소개, 작가 키워드를 불러올 것이다.다만 이 값들은 모두에게 같은 정보를 보여주는 걸까? 당연히 아니다. 사용자 A에게는 A의 정보를, 사용자 B에게는 B의 정보를 불러줄 것이다. 그럼 어떤 사용자의 정보를 불러와줄지 API는 어떻게 구분할 수 있을까? 결국 사용자를 구분하기 위한 정보-회원 아이디, 회원번호 등-를 알려줘야 할 것이다.
API에서 값을 불러와주려면 그 값을 불러오기 위해 입력해야 하는 값도 존재한다.SWAGGER에서 만약 특정 값을 불러오는 GET 메소드의 API를 찾았다고 하더라도, 구체적으로 불러올 값을 확인하기 위해서, 입력해야 값이 존재한다. 즉 회원번호 1을 입력하면 회원번호가 1인 사용자의 프로필 정보를 불러와주는 식이다.
SWAGGER에선 그래서 해당 API를 이용(호출) 하기 위해 직접 넣어줘야 하는 값들의 예시와 그 서식을 확인할 수 있다. 그리고 그 값을 입력한 뒤 "Try it out"을 클릭하면 해당 API를 이용(호출)할 수 있다.
GET 메소드 API를 이용(호출) 하기 위한 예시. 입력해야 하는 값(파라미터)과 그 서식이 설명되어있다.
빈칸에 규칙에 맞게 값을 입력 후 Try it out을 클릭하면 해당 API를 이용(호출)하게 된다
필요한 값(파라미터)을 넣고 이용(호출) 한 결과의 예시. 200,400,500 번대 등의 결과 코드와 함께 돌아오는 값이 설명되어있다. 이처럼 해당 API를 규칙에 맞게 값(파라미터)을 넣고, 그것이 다시 불러와주는 값을 확인하면 해당 API에서 구체적으로 어떤 정보가 어떤 형식으로 어떻게 오가는지 확인할 수 있다.
즉 API를 확인한다는 건 무슨 값parameter를 넣으면, 무슨 결과-어떤 값이, 어떤 형식으로 어떻게-가 돌아오는지를 보는 것이다.
이어지는 다음 글에선
- 기획 내용과 현재의 API가 다를 때의 이슈 또는 커뮤니케이션 사례들과
- 기획과 API가 다르지만 큰 이슈가 아닐 때 (또는 백엔드 개발자가 작업을 하지 않아도 되는 때)
에 대해 정리하고자 한다
