postman-mock Server 사용하여 API명세서 작성 후 테스트하기

지금부터 몰입을 해봅시다.

우린 맛집정보를 찾아주고 지도 근처에 맛집 정보를 불러와서 사용자에게 나타내 주는 서비스를 만드는 팀입니다.

해서 지금부터 맛집관리 API를 먼저 설계하고,

postman - mock server를 사용해서 실제 테스트까지 진행 후 프론트에서 실제 동작하는 것을 확인 해보도록 하겠습니다.

1. API 식별하기

그전에 http/api 개념에 대해서 한번 짚고 넘어가봅시다.

우리가 브라우저에 주소를 입력하면, 브라우저가 "오! 이주소로 이동해달라고? ㅇㅋ" 하고 바로 해당 아이피를 121.000. 이런식으로 리턴하지 않습니다.

 

먼저 우리가 주소를 입력하면 dns서버에 "place.map.kakao" 를 쓰는 아이피를 알려줘~ 하고 요청을하고 dns서버가 어~ 그거는

121.53.107.190이야~ 하고 리턴을 해주고 이제 클라이언트(브라우저)가 실제 해당 아이피 주소에

html파일을 요청합니다.

"사용자가 너네 아이피 화면 띄워달래 html내놔." 하는거죠.

그러고 한줄씩 읽다보니 "여기 부분은 css가 필요하네?" "js가 필요하네?" 판단을하고 해당 파일들을 요청을 합니다.

(여기서 궁금한건 next.js, tailwind같은경우엔 처음에 다 불러오는가, server side인 경우에는 한번에 다 그려서 가져온다고 들었는데 그런경우는 요청방식이 다른것인가?) 

 

이후 필요한 정보들 (ex. 메뉴 리스트 등) 을 api를 통해 서버에 요청을합니다.

카카오 맵 예시 API의 기본적인정보들을 보면,

• Request URL: https://place-api.map.kakao.com/places/panel3/10332413
  • 서버에 카카오 맵 장소 정보를 찾기 위한 url로 ID가 10332413인 명동교자 본점 정보를 찾습니다.
• Request Method: GET
  • GET(조회) 하는 요청입니다.
• Status Code: 200 OK
  • 요청이 성공적으로 처리되었습니다.
• Remote Address: (접속 IP, 예: 211.249.220.xxx:443)
  • DNS 서버를 통해 교환된 211.249.220.22:443 IP 주소로 요청을 보냅니다.

이API는 별도의 복잡한 Request Body나 쿼리 파라미터 없이, URL 경로(Path) 자체에 핵심 정보를 담아 요청합니다.

• Endpoint 구조: /places/panel3/{confirm_id}
• 파라미터: 10332413
  • 카카오맵 서버에 저장되어 있는 명동교자 본점의 고유 ID를 url에 동봉하여 전달합니다.

1. 응답

Preview 또는 Response 탭을 통해 확인한 Response Body에 JSON 데이터는 명동교자 본점의 상세 정보를 담고 있습니다.

 

2. API 명세서 만들기

자 그럼 이제 기본적인 api 명세서를 한번 만들어봅시다.

1️⃣ 목적

• API 구조와 RESTful API 설계 방법을 복습합니다.
• 맛집 관리에 필요한 API를 스스로 설계합니다.

2️⃣ 내용

1. 맛집(place) 을 관리하기 위한 기능(행위)인 등록, 전체 조회, 삭제 API를 각각 작성해야합니다.

맛집(place) 관리를 위한 데이터를 JSON 형태로 정의합니다.데이터 명 키 값 (예시)

아이디	id	1
이름	name	“명동교자 본점”
주소	address	“서울 중구 명동10길 29 1층”
전화번호	call	“02-776-5348”
카테고리	category	“한식”
평점	rating	5
메뉴	menu	[{name , price}]
이미지 url	main_image_url	메인 이미지 url

 

시간이 조금 더 있었다면 조금 더 괜찮은 구조를 만들 수 도 있지만, (이미지를 id로 매핑등) , 나는 과제 제출 당일에 이걸 받았기 때문에..일단 이렇게만 만들었다.

 

📌  등록

Request -

• Method: POST.
• URL: http:localhost:3000/place
• Content-Type: strict-origin-when-cross-origin
• Body:

  **{
  	name : 이름,
  	address : 주소,
  	number : 전화번호,
  	category : 카테고리,
  	menu : {
  		name : 이름
  		price : 가격
  	}[],
  	rating : 별점,
  	main_image_url : 이미지 url
  }**
  ​

  Response
  • Status Code: 201.

**{
	result : "등록에 성공하였습니다"
}**

 

사실 급해서 바디에 아무 데이터도 안넣고 일단 result 박았는데

[
  {
    "id": 1,
    "name": "명동교자 본점",
    "address": "서울 중구 명동10길 29 1층",
    "call": "02-776-5348",
    "category": "korean",
    "rating": 5
  },
  {
    "id": 2,
    "name": "스파르타 치킨",
    "address": "서울 강남구 테헤란로 123",
    "call": "02-123-4567",
    "category": "chicken",
    "rating": 4.5
  }
]

이런식으로 바디에도 등록된 데이터를 담아 리턴해줘야 클라이언트도 데이터가 잘 등록이 되었는지 2차 검증이 가능할듯하다.

 

📌  전체 조회

Request - 요청

• Method: GET.
• URL: http:localhost:3000/place
• Content-Type: strict-origin-when-cross-origin

Response

• Status Code: 200.
• Body:

  **{
  	id: index,
  	name : 이름,
  	address : 주소,
  	number : 전화번호,
  	category : 카테고리,
  	menu : {
  		name : 이름
  		price : 가격
  	}[],
  	rating : 별점,
  	main_image_url : 이미지 url
  }**
  ​

삭제

Request -

• Method: delete.
• URL: http:localhost:3000/place?placeId=id
• Content-Type: strict-origin-when-cross-origin
• Path Parameters:키 값

  placeId

  id

Response

• Status Code: 200.
• Body:

• **{
  	result : "삭제 성공하였습니다 : {id}"
  }**
  

 

이렇게 간결하게 api 명세서를 작성을 해보았다. 내가 실제로 개발업무를 했을때 다른 기업에서 받은 api명세서들은 그것만 보고는 개발이 불가능 할만큼 복잡하고 조건이 너무 많고 무엇보다 본인들만 아는 단어들을 사용하여 힘들었는데.(내가 도메인 이해도가 떨어졌던 걸지도..)

이렇게 간단한 서비스는 명세서만으로도 충분히 개발이 가능할 듯하다.

 

3.postman으로 api 검증하기

사실 이건 처음해보는데. postman자체는 알고있다 다만 똑바로 활용해본적이 없다...왜냐면 나는 항상 swagger를 작성해서 했기 때문이다.

여튼 그래서 swagger mock이 정확히뭔지 조금 더 공부할 시간이 있었다면 좋았겠지만 급하게 진행을 한만큼(거의 20분..?) 잘못 작성했던 부분도 있어서 강의를 듣고 아~ 원래는 이런거구나~ 하는 부분을 적어보겠습다.

 

일단 postman이 무엇이냐. 간단하게 그냥 내가 작성한 코드 테스트 돌려볼 수 있는 공간이다 이거입니다.

처음에 워크 스페이스 들어오면 원래 저기에 왼쪽에 아무것도 없습니다.

원하는 이름으로 collections 를 만들어 주고 그안에서 내가 원하는 url을 만들어 줍시다.

 

그리고 이거 정말 많이 햇갈렸습니다. 

저 request 에서 점 3개 혹은 우클릭 후 add example 하면 저는 이게 뭔가 했는데 request 시도하면 나오는 결과 샘플을 여기서 설정 할 수 있더군요.. 개꿀이롭니다...

 

이런게 있다니.. .허허...해서 

example

결과

!주의! 저 SVAE버튼 무적권 무적~권 누르십쇼

여튼 그리고 이제 mockServer 를 만드시고, 만드실때

Save the mock server URL as an new environment variable 이거 체크하시는게 편할듯합니다.

오른쪽위에 환경 변수를 설정해주면 이런식으로 URL만 입력해도 자동으로 환경변수 세팅이됩니다.

{{url}}/place

완전 편하죠?