[과제]맛집 관리 API 설계하기(튜터님 피드백 반영)

• 과제명 : CH 1 맛집 관리 API 설계하기
• N기 제출자 : [Spring 2기] 전민우

필수 기능

1.API 식별하기

-https://place.map.kakao.com/10332413 링크로 이동하여

개발자 도구로 *https://place-api.map.kakao.com/places/panel3/10332413 인 API 찾기

 

[문제]어?....API 어디서 확인했지?...많은내용을 학습하다 보니.. 어디서 확인하는지 헷갈리기 시작했다.

[해결]침착하게 네트워크에서 문서 패쓰 JS 등 각 탭내용을 확인하여 있는 위치를 하기와 같이 찾을수 있었다.

 

 

-Header 탭에서 url, method, status code, content-type 등 요청-응답이 어떤 정보로 이루어지는지 확인합니다.

 

클라이언트→서버 요청을 보낸 헤더 정보

place-api.map.kakao.com의 서버에 있는 /places/panel3/10332413 이곳에 정보를 불러와 주세요 (GET) https의 규약을 사용하여 요청을 보냅니다. 응답을 보내주실때에는 application/json, text/plain, */* 이러한 형태로 보내주시면 제가 확인할수 있습니다.

 

서버→클라이언트 응답을 보낸 헤더 정보

응답은 application/json으로 보내드렸습니다. 보내주신 요청 문제없이 잘 처리되었습니다. (200 OK)

 

-Preview 탭에서 어떤 데이터를 응답해주었는지 확인합니다.

실제 클라이언트 화면에서 확인할수 있는 정보들을 응답받았습니다.

타이틀,리뷰갯수,리뷰이미지,근처 지하철역 정보,영업중인지 아닌지, 메뉴정보, 포장가능여부, 등등등

 

-API 정보(URL, Method, Status, Content-Type)와 Request Body, Response Body의 구조(어떤 데이터가 오는지)를 바탕으로, "이 API가 어떤 요청을 받아 어떤 응답을 주는지 분석합니다.

 

요청 헤드에는 place-api.map.kakao.com의 서버에 있는 /places/panel3/10332413 이곳에 정보를 불러와 주세요 (GET) https의 규약을 사용하여 요청을 보냅니다. 응답을 보내주실때에는 application/json, text/plain, ‘/’ 이러한 형태로 보내주시면 제가 확인할수 있습니다.

응답은 application/json으로 보내드렸습니다. 보내주신 요청 문제없이 잘 처리되었습니다. (200 OK)

실제 클라이언트 화면에서 확인할수 있는 정보들을 응답받았습니다.

타이틀,리뷰갯수,리뷰이미지,근처 지하철역 정보,영업중인지 아닌지, 메뉴정보, 포장가능여부, 등등등

 

결론 : 클라이언트는 API에게 해당 점포의 정보들을 요청하는 GET을 보냈고, API는 확인하여 점포 정보들을 담은 Body로 응답하였습니다.

 

 

2.API 명세서 만들기

 

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

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

아이디	id	1
이름	name	“명동교자 본점”
주소	address	“서울 중구 명동10길 29 1층”
전화번호	call	“02-776-5348”
카테고리	category	“한식”
평점	rating	5

 

 

등록, 전체 조회, 삭제 API를 작성해주세요.

• 맛집 (place) 등록 API 명세서 템플릿
• Request - 요청
  • Method: post
  • **URL:**place-api.map.kakao.com
• [문제]파라미터 주소를 입력하였으나, 입력을 하는부분이 아니였다.
• [해결]파라미터 주소는 삭제할때 특정 id값을 지정시 그뒤에 붙는 값으로 등록을 요청할때는, 지정값이 없음으로 작성을 x
• 키 값

  name	"명동교자 본점",
  address	"서울 중구 명동10길 29 1층"
  call	"02-776-5348"
  category	"한식"

  • Content-Type: application/json
  • Body:

  • {
    	"name": "명동교자 본점",
    	"address": "서울 중구 명동10길 29 1층",
    	"call": "02-776-5348",
    	"category": "한식"
    }
    

    
    튜터님 피드백 : 등록 API에서 rating 필드를 데이터 정의 표에는 넣어두었지만, Request Body에는 포함되지 않고 Response에만 나타나 있습니다. 실제 설계를 생각하면 요청과 응답에서 필드 구성이 어떻게 다른지(입력값 vs 서버가 채우는 값) 를 의도적으로 나눌지, 아니면 동일 필드를 사용할지를 명확히 해두면 좋겠습니다.
• Response
  • Status Code: 201 Created
  • Body:

  • {
    	"id": 1,
    	"name": "명동교자 본점",
    	"address": "서울 중구 명동10길 29 1층",
    	"call": "02-776-5348",
    	"category": "한식",
    	"rating": 5
    }
    

    [문제]rating 5뒤에 , 를 붙여서 문법적 오류가 발생[해결]Postman의 오류창으로 확인하여 수정하였다. 앞으로 제발 문법적 오류를 범하지 않도록 디테일에 신경써야겠다.
    
    • 맛집 (place) 전체조회 API 명세서 템플릿
    • Request - 요청
      • Method: get
      • URL: place-api.map.kakao.com
      키 값->없
      • Content-Type: application/json
      Response
    • 튜터님 피드백 :  전체 조회 API의 Response 예시는 현재 단일 객체 한 건만 내려주고 있지만, “전체 조회”라면 [{...}, {...}] 형태의 배열(Array)로 예시를 정리하는 것이 REST API 문서 관점에서 더 자연스럽습니다. 이 부분만 정리해도 명세 읽는 사람이 훨씬 이해하기 쉬워집니다.
      • Status Code: 200 OK
      • Body:

      • {
        	"id": 1,
        	"name": "명동교자 본점",
        	"address": "서울 중구 명동10길 29 1층",
        	"call": "02-776-5348",
        	"category": "한식",
        	"rating": 5
        }
        .
        .
        .
        .
        .
        
        ​

        • 맛집 (place) 삭제 API 명세서 템플릿Request - 요청
          • Method: delete
          • 튜터님 피드백 : 삭제 API에서 URL을 place-api.map.kakao.com / places/panel3/{id}로 적어두었는데, 이 과제의 도메인을 기준으로 보면 /places/{id} 정도로 단순하게 가져가는 것이 REST스럽습니다. 또한 DELETE는 일반적으로 204 No Content에 Body 없이 처리하거나, 메시지를 주고 싶으면 200 OK + Body로 처리하는 식으로 하나의 패턴만 선택하는 연습을 해보시면 좋겠습니다.
          • URL: place-api.map.kakao.com
          • Path Parameters: /places/panel3/{id}키 값

            id

            1

          • Content-Type: application/json
          Response
        • [문제]메세지 출력이 되지않고 1만 출력되는 현상
        • [해결]204 No Content 입력시 메시지가 출력되지 않고, 200 OK 입력시 메세지 출력이 가능하다.
          • Status Code: 204 No Content or 200 OK[메세지 출력을 위해서]
          • Body:

            {
            	"message": "삭제되었습니다."
            }
            ​

  •  

튜터님 피드백 : API Response는 성공과 실패를 포함해 모든 응답이 동일한 규격을 따르도록 통일해야 하며, 이는 협업과 유지보수를 쉽게 만들어줍니다. 그렇기에 아래와 같은 예시로 성공,실패 여부를 넣어보는 연습부터 응답규격을 규칙적으로 만들어내보는 연습까지 천천히 해보시면 좋습니다. ex): { "success": true, "data": { "id": 10 } }

[나의 깨달음] 클라이언트 개발자는 응답이 오면 무조건 success 키의 값을 먼저 확인하고, true일 때만 data를 사용하면 되므로 코드를 짜기가 매우 쉬워진다.

 

예외 처리에 대한 응답도 지금부터 천천히 고민하고 작성해보는 연습을 해보시면 좋습니다. 예외 응답도 일정한 형식을 유지해야 하며, 오류를 식별할 수 있는 errorCode와 메시지를 포함해 사용자에게 명확한 정보를 전달해야 합니다.

 

Ex): { "success": false, "errorCode": "USER_NOT_FOUND", "message": "사용자를 찾을 수 없습니다." }

[나의 깨달음]성공 응답만큼이나 오류 응답도 일정한 형식을 유지해야 클라이언트가 오류를 정확하게 처리할 수 있다.

2. 오류 응답에 명확한 식별 정보 포함

• success: false: 일단 실패했음을 명확히 알립니다.
• errorCode (오류 코드): 오류의 종류를 컴퓨터가 식별할 수 있는 고유한 문자열로 제공합니다.
  • 예시: USER_NOT_FOUND (사용자를 못 찾음), INVALID_INPUT (입력값이 잘못됨)
  • 효과: 클라이언트가 이 코드를 보고 "이 오류는 로그인 실패구나" 또는 "이 오류는 입력 양식 오류구나"를 판단하여, 사용자에게 보여줄 메시지를 다르게 처리할 수 있습니다.
• message (오류 메시지): 해당 오류에 대한 사람이 읽을 수 있는 설명을 제공합니다.
  • 예시: "사용자를 찾을 수 없습니다.", "비밀번호가 일치하지 않습니다."

.

 

Path Parameter는 {id}처럼 표현만 해두는 것이 아니라 실제 값이 들어간 예시를 함께 제공해야 하며, 이를 통해 클라이언트가 어떤 값을 넣어야 하는지 명확히 이해하도록 돕습니다. 예시: GET /products/42 (상품 ID 42 조회)

[나의 깨달음] Path Parameter란? URL 경로의 일부분에 변하는 값을 넣는 방식 (예: 특정 상품의 ID, 특정 유저의 이름 등)

GET /products/42->이 예시를 통해 클라이언트는, 나는 상품 ID인 42 같은 숫자를 넣어서 요청해야 하는구나 라고 명확하게 이해하게 된다.

 

 

3.Mock 서버 구축하기

Mock 서버 검증은 도전기능 2번째 문제에 기재되어있습니다.

[문제]Request시 Response가 정상출력되지 않는 현상 발생

[해결]Mock서버를 새로 개설하여 해당 쿼리를 독립연결하여 해당 문제를 해결

 

place API.postman_collection.json

0.01MB

 

 

도전 기능

(1) v0로 맛집 관리 프로젝트 프론트엔드 구현하기

[칭찬]강의때 들은 내용을 기반으로 질의를 하였더니, 1번만에 프롬포트가 잘 개설 되었다.

• 프롬프트(텍스트)와 완성한 결과물 zip 파일을 첨부해주세요.

 

restaurant-management-frontend.zip

0.23MB

 

(2) 완성된 프론트엔드와 mock 서버 연동하기

• 맛집을 추가했을때, 프론트엔드와 Mock 서버 간 요청-응답 흐름을 그림이나 글로 작성하세요. (하나만 선택해서 업로드해주셔도 괜찮아요.)

Mock 등록

 

Mock 전체조회

 

Mock 삭제

 

인텔리제이 Mock 서버 연동

 

등록 데이터 응답 값

 

 

맛집 목록 응답 값

 

맛집 삭제 응답 값

 

 

서버와 통신 결과 

 

[문제] 개설된 프롬포트에서 기능을 구현하였으나, 맛집 추가도, 삭제, 조회를 해도 똑같은 화면만 반복

[해결]연결된 Mock서버는 정해진 응답만 반응함으로, 추가,조회,삭제가 이루어지지 않은것처럼 보일수 있으나,

         실제로 프롬포트 개발자 도구를 활용해 정상 요청과 응답이 오는것을 확인할수 있다.

 

v0로 만든 프롬포트를 다운받아 인텔리제이에서 엔드포인트 부분에, URL을 Mock서버 URL으로 수정하면서

연동을 마무리 하였습니다.

최종으로 프롬포트에서 각종 기능을 테스트 하며 실제 서버와의 통신이 정상 작동을하는지 개발자 도구를

활용하여 요청과 응답내용을 Mock서버 셋팅값과 비교하여 과제를 마무리 하였습니다.

 

프론트엔드부터 서버까지 전체적으로 데이터의 흐름과 각 역할을 이해할수있었던 과제였습니다.

 

 

 

 

-----------------------------------------------------------------------------------------------------------------------------

튜터님 종합 피드백

 

과제 평가 -완성도

튜터 1:1 피드백

담당자 : 박성규 튜터

안녕하세요 민우님! 과제 해결하시느라 수고 많으셨습니다. 아래는 제출해주신 과제에 대한 피드백입니다. [잘 작성된 부분] -카카오맵 API를 Network 탭에서 직접 찾아 Header와 Preview 탭으로 나누어 설명한 점이 좋았습니다. 요청·응답을 사람 간 대화처럼 풀어쓴 부분은 HTTP 흐름을 감각적으로 이해하는 데 도움이 되었을 것 같습니다. -Header에서 URL, Method, Status Code, Content-Type을 짚고, Preview에서 실제 화면에 보이는 정보(타이틀, 리뷰 개수, 영업 여부, 메뉴 정보 등)가 어떻게 JSON으로 내려오는지 연결해 본 점이 인상적이었습니다. “데이터 → UI” 흐름을 잘 짚었습니다. -맛집 등록/전체 조회/삭제 API를 하나의 도메인(place)에 맞춰 묶고, 공통 필드(id, name, address, call, category, rating)를 먼저 표로 정의한 뒤 각 API 명세로 내려간 점은 구조적으로 잘 작성했습니다. -Mock 서버를 Postman Collection으로 구성하고, v0로 생성한 프론트엔드를 인텔리제이에서 열어 Mock 서버 URL로 교체해가며 실제로 호출을 검증한 과정이 좋았습니다. 마지막에 개발자 도구로 요청·응답과 Mock 서버 셋팅값을 비교한 것도 실무적인 검증 방식이었습니다. -도전 기능까지 포함해서, “프론트엔드 ↔ Mock 서버 ↔ API 명세”를 한 사이클로 경험해보고 마무리 소감에서 데이터 흐름과 각 레이어 역할을 언급한 점이 학습 과정 정리 측면에서 좋았습니다. [개선이 필요한 부분] -등록 API에서 rating 필드를 데이터 정의 표에는 넣어두었지만, Request Body에는 포함되지 않고 Response에만 나타나 있습니다. 실제 설계를 생각하면 요청과 응답에서 필드 구성이 어떻게 다른지(입력값 vs 서버가 채우는 값) 를 의도적으로 나눌지, 아니면 동일 필드를 사용할지를 명확히 해두면 좋겠습니다. -전체 조회 API의 Response 예시는 현재 단일 객체 한 건만 내려주고 있지만, “전체 조회”라면 [{...}, {...}] 형태의 배열(Array)로 예시를 정리하는 것이 REST API 문서 관점에서 더 자연스럽습니다. 이 부분만 정리해도 명세 읽는 사람이 훨씬 이해하기 쉬워집니다. -삭제 API에서 URL을 place-api.map.kakao.com / places/panel3/{id}로 적어두었는데, 이 과제의 도메인을 기준으로 보면 /places/{id} 정도로 단순하게 가져가는 것이 REST스럽습니다. 또한 DELETE는 일반적으로 204 No Content에 Body 없이 처리하거나, 메시지를 주고 싶으면 200 OK + Body로 처리하는 식으로 하나의 패턴만 선택하는 연습을 해보시면 좋겠습니다. - API Response는 성공과 실패를 포함해 모든 응답이 동일한 규격을 따르도록 통일해야 하며, 이는 협업과 유지보수를 쉽게 만들어줍니다. 그렇기에 아래와 같은 예시로 성공,실패 여부를 넣어보는 연습부터 응답규격을 규칙적으로 만들어내보는 연습까지 천천히 해보시면 좋습니다. ex): { "success": true, "data": { "id": 10 } } - 예외 처리에 대한 응답도 지금부터 천천히 고민하고 작성해보는 연습을 해보시면 좋습니다. 예외 응답도 일정한 형식을 유지해야 하며, 오류를 식별할 수 있는 errorCode와 메시지를 포함해 사용자에게 명확한 정보를 전달해야 합니다. Ex): { "success": false, "errorCode": "USER_NOT_FOUND", "message": "사용자를 찾을 수 없습니다." } - Path Parameter는 {id}처럼 표현만 해두는 것이 아니라 실제 값이 들어간 예시를 함께 제공해야 하며, 이를 통해 클라이언트가 어떤 값을 넣어야 하는지 명확히 이해하도록 돕습니다. 예시: GET /products/42 (상품 ID 42 조회)

 

과제 평가 -이해도

튜터 1:1 피드백

담당자 : 박성규 튜터

모든 항목을 달성한 것을 보면 단순히 툴을 사용하는 수준을 넘어서, HTTP 구조와 요청–응답의 전체 흐름을 실제 서비스 관점에서 이해하고 있다는 점이 분명하게 드러납니다. 단순히 API를 호출하는 것이 아니라, 이를 설계하고, 명세로 문서화하고, Mock 서버를 활용해 사전 검증까지 수행한 뒤 FE와 연결해 흐름을 완성하는 과정 전반을 스스로 논리적으로 이어갈 수 있는 능력을 갖추었다는 뜻입니다. 특히 Network 탭을 통해 API를 분석하고, RESTful 원칙에 맞춘 명세를 작성하며, 적절한 Method·URL·Query·Body·Status Code를 정확하게 구분해낸 점은 실무 개발에서 매우 중요하게 평가되는 부분입니다. 또한 프론트엔드 구현을 위한 사전 컨텍스트를 정리하고, 이를 기반으로 프롬프트를 구성해 AI를 활용해 FE까지 생성한 과정은 학습자로서 높은 수준의 자기 주도성을 보여줍니다. 이제부터는 기술 사용 능력에서 한 단계 더 나아가, API 문서 자동화(Swagger), 전역 예외 처리와 에러 응답 표준화 같은 확장 영역을 학습해보면 좋습니다. 이러한 기능들은 팀 단위 협업과 실제 서비스 운영 경험을 더 탄탄하게 만드는 핵심 요소입니다. 지금처럼 요청–응답 전 과정을 하나의 흐름으로 이해하고 연결하는 방식의 학습을 지속한다면, 실무 환경에서도 빠르게 적응하고 성장할 수 있을 것으로 보입니다.

과제 평가 -우수성

튜터 1:1 피드백

담당자 : 박성규 튜터

모든 항목을 달성한 것으로 보아, 단순히 기능을 구현하는 수준을 넘어 HTTP 구조와 RESTful 원칙, 그리고 요청·응답 전반의 흐름을 스스로 해석하고 실제 작업에 적용할 수 있는 단계에 도달한 것으로 판단됩니다. 이는 백엔드 학습에서 가장 중요한 기반이며, 단순히 코드를 작성하는 것을 넘어서 “왜 이렇게 동작하는가”를 이해하고 있다는 점에서 이미 우수한 성장 속도를 보여주고 있습니다. 특히 Method, URL, Query Parameter, Body, Status Code를 정확하게 구분하고 이를 API 명세서에 반영한 부분은 실무에서도 높은 완성도로 평가받는 요소입니다. 이러한 명확한 구분 능력은 협업 과정에서 요구사항을 정확하게 전달하고, FE와의 소통에서도 불필요한 혼선을 줄이는 데 큰 역할을 합니다. 또한 프론트엔드를 구현하기 위한 사전 컨텍스트를 정리하고, 이를 기반으로 프롬프트를 구성해 실제로 백엔드 API 검증까지 수행한 것은 매우 훌륭합니다. 이는 백엔드와 프론트엔드가 어떤 방식으로 데이터를 주고받으며 전체 서비스가 완성되는지 깊이 이해하고 있다는 확실한 신호입니다. 단순한 호출 테스트가 아니라, 전체 흐름을 연결해 보려는 사고 방식 자체가 이미 실무 개발자가 가져야 할 시각과 매우 유사합니다. 전반적으로 매우 안정적인 학습 속도와 높은 이해도를 보여주고 있으며, 지금과 같은 방식으로 학습을 이어간다면 실무 환경에도 빠르게 적응할 수 있을 것으로 기대됩니다.