search

Chance-Glance / server

뭐하고 no car 서버입니다.
0 stars 1 forks source link

축제 주변 장소 관련 API 엔드포인트 수정 제안 #26

Open mungsil opened 1 week ago

mungsil commented 1 week ago

📄 이슈 내용

축제 주변 장소 관련 API 엔드포인트 수정을 제안드립니다. 현재 축제 주변 장소와 관련된 API 엔드포인트는 다음과 같습니다.

GET /api/v1/nearby-places/{festivalId}
PATCH /api/v1/nearby-places/update

  1. GET /api/v1/nearby-places/{festivalId} 수정 제안 REST API에서 슬래시는 계층 관계를 나타냅니다. 축제와 축제 주변 장소의 관계를 생각해본다면, 축제가 축제 주변 장소보다 상위 개념일 것입니다. 이는 축제라는 리소스가 존재해야 축제의 주변 장소라는 리소스가 생겨날 수 있기 때문입니다.

    하지만 현재 GET /api/v1/nearby-places/{festivalId}의 설계를 살펴보면, nearby-places가 더 상위 계층에 존재하고 있어요. 따라서 이는 옳지 않은 설계라고 생각했습니다.

    또한, 해당 엔드포인트가 나타내고자 하는 리소스가 명확히 드러나지 않고 있어요. GET /api/v1/nearby-places/{festivalId} 가 실제로 사용될 때는, GET /api/v1/nearby-places/3 과 같은 형태로 사용됩니다. 따라서, festivalId인 3이 무엇을 나타내는지 모호하다는 것을 알 수 있어요. nearby-places, 즉 주변 장소의 id가 3인 것과 같이 느껴질 수도 있거든요.

  2. PATCH /api/v1/nearby-places/update 수정 제안 REST API에서 동사는 HTTP 메서드로 나타내는 것이 좋은 설계입니다. 또한, update를 리소스에 작성해주지 않아도 PATCH를 통해서 nearby-places를 업데이트 한다는 의미가 충분히 전달될 수 있어요. PATCH 메서드는 자원의 일부분을 업데이트할 때 사용하는 HTTP 메서드이기 때문입니다.

최종 제안

GET /api/v1/festivals/{festivalId}/nearby-places
PATCH /api/v1/festivals/nearby-places

이와 같이 API 설계를 변경한다면, 가독성을 향상시키고 의미 전달을 더욱 명확히 할 수 있을 것 같습니다. 더 나은 설계 방향이 있다면, 자유롭게 코멘트 남겨주시면 감사하겠습니다.

mingmingmon commented 1 week ago

1번 개선사항에 대해서는 동의합니다!

2번 개선사항의 경우에는 해당 엔드포인트에서 축제 주변 장소 정보 수집을 위해 외부 API를 호출하는 것으로 알고 있습니다. 그리고 그 과정에서 얻은 정보를 RDS에 저장하고 있죠. 그렇게 되면 해당 엔드포인트는 축제 주변 장소 정보를 사용자가 수정(PATCH)하는 동작이 아닌 셈입니다. API로 노출되어있는 것은 클라이언트와의 소통이 필요하여 interface를 제공하는 것에 의미가 있는데, 해당 API는 그런 동작보다는 서비스 자체적으로 새로운 정보를 업데이트하여 DB에 저장하는 로직을 담고 있습니다.

현재 상황으로는 주기적인 DB 업데이트가 안 돼서 이 기능을 API로 뽑아 스웨거 상에서 처리하고 있는 것으로 알고 있습니다. 따라서 PATCH /api/v1/festivals/nearby-places 보다는 PATCH /api/v1/festivlas/nearby-places/load라는 식으로 적재하는 의미를 살리는 쪽은 어떻게 생각하시나요?

mungsil commented 1 week ago

말씀해주신 것처럼, 현재 PATCH /api/v1/festivals/nearby-places는 설계 의도와 다른 동작을 하고 있습니다. 업데이트가 아닌, 적재의 역할을 하고 있어요. 원래는 이 부분을 고려하여, 추가적으로 API 명세서(스웨거)에 의도된 바와 다른 동작을 하고 있음을 명시하려고 했었어요.

하지만, 제시해주신 대안인 적재의 의미를 살리는 엔드포인트로 변경 또한 타당한 의견입니다. 따라서 엔드포인트가 다르게 수정되어야 한다는 의견에 동의합니다. 예시로 들어주신 PATCH /api/v1/festivlas/nearby-places/load 도 적재의 의미를 살린다는 점에서 좋습니다.

다만, 해당 엔드포인트는 URI에 동사를 사용하고 있어요.RESTful API에서 URI에는 동사 사용을 지양하고, 명사 위주로 표현하는 것이 좋습니다.

따라서 POST /api/v1/festivlas/nearby-places 와 같은 설계를 제안드려요. POST는 다양한 상황에서 사용될 수 있는 HTTP 메서드 입니다. 따라서 외부 API에서 데이터를 가져와 저장하고 있는 현재 상황에도 사용될 수 있으며, 추후 업데이트 로직이 완성되었을 때도 충분히 사용 가능한 엔드포인트라고 생각해요. 이와 더불어 명세서에 업데이트 로직이 구현될 예정임을 설명해놓는 것은 어떨까요?

mingmingmon commented 1 week ago

POST /api/v1/festivlas/nearby-places로 진행하는 것이 적절한 것 같습니다! 또한 명세서에 추가 설명을 달아두는 것도 동의합니다.