팀 프로젝트

[설계] RESTful 하게 API 짜기

wintertreey 2024. 8. 15. 15:11

 
내가 담당한 화면들에 구현할 기능은 다음과 같다. 

해당 화면은 내가 짠 다이어그램을 기반으로 프론트를 맡으신 동료님께서 작업툴(figma)로 만들어주셨다.
 
<장소 >
1. 카테고리별 장소 조회
/places?category=aa
2. 카테고리 및 키워드로 장소 조회(단순한 검색기능)
/places?category=aa&keyword=bb
3. 선택 장소 1개 조회
/places/{p_no}
 
Q.
2번 기능을 구현할때 검색한 키워드 값이 주소나 시설명과 매칭되는지를 확인해야했다. keyword라고 지칭했는데..
api 짤때 db의 칼럼명과 반드시 매칭되어야 할까? 혹시 이건 RESTful에 어긋나지는 않을까?

A.

RESTful API에서 엔드포인트와 쿼리 파라미터는 실제 데이터베이스 컬럼과는 관계가 없으며, API의 요구 사항에 맞게 쿼리 파라미터를 설계하여 데이터를 필터링하거나 검색할 수 있습니다

 

작업시 sql문

SELECT * FROM place WHERE p_category = ? AND (p_name LIKE ? OR p_address LIKE ?);

여기서:

  • ?는 쿼리 파라미터로 바인딩되는 값입니다.
  • p_category = ?는 카테고리 필터를 적용합니다.
  • (p_name LIKE ? OR p_address LIKE ?)는 키워드를 이름이나 주소에서 검색합니다.

 
 
Q. 
1과 2의 경우 복수개의 장소를 조회하기에 /places인데, 3의 경우 1개의 장소를 조회하기에 사실 목적에 부합하자면 /place가 맞지 않을까? 
 
A. places로 통일.
1. 기능의 목적에 맞게 /places와 /place 나누기

  • 단일 장소 조회: /places/{p_no}
  • 설명: 단일 장소를 조회하는 경우, p_no를 사용하여 고유하게 식별된 리소스를 조회합니다. 여기서 단일 장소를 의미하는 place를 사용할 수 있지만, 복수형으로 사용해도 문제는 없습니다. /places/{p_no}라고 하더라도 일관성을 유지할 수 있습니다

2. 일관성 유지와 테이블명에 맞추기

  • 단일 리소스: 단일 리소스를 조회할 때는 /place/{p_no}와 같이 단수형을 사용하는 것이 명확할 수 있습니다. 하지만 RESTful 설계에서는 /places/{p_no}와 같은 형식을 사용해도 문제가 없습니다.

 
<장소의 리뷰>
1. 장소의 리뷰들 조회
GET /places/{p_no}/reviews
2. 장소의 리뷰 생성
POST /places/{p_no}/reviews
3. 장소의 리뷰 수정
PUT /reviews/{r_no}
4. 장소의 리뷰 삭제
DELETE /reviews/{r_no}
 
Q. 리뷰의 수정, 삭제시 꼭 앞부분에 장소의 정보를 들고 가야할까? 불필요하지 않을까? 
 
A. 불필요. 리뷰의 번호만으로도 해당 리뷰를 특정할 수 있으니. 장소에 대한 정보도 불필요하니까. 
 

  • 리뷰 생성 및 조회: 장소(p_no)와 관련된 리뷰를 다루기 때문에 places/{p_no}를 URL에 포함합니다.
  • 리뷰 수정 및 삭제: 리뷰 자체를 식별하기 위해 r_no만 필요하므로, 장소를 URL에 포함할 필요가 없습니다.

 

++ 실제로 로직을 구현하며 컨트롤러에서 @GetMapping() 어노테이션을 적으며 경로설정을 해주다보니 궁금해진 부분.

/places?pCategory=aa  
vs
/places/pCategory{pCategory}


/places?pCategory=aa와 /places/pCategory{pCategory}는 RESTful API 설계에서 서로 다른 방식으로 URL을 사용하여 요청을 처리하는 두 가지 방법입니다. 차이점은 다음과 같습니다:

1. 쿼리 파라미터 (/places?pCategory=aa)

  • 사용 예: /places?pCategory=aa
  • 설명: 쿼리 파라미터는 URL의 ? 뒤에 key=value 형식으로 추가되는 파라미터입니다. 여러 개의 쿼리 파라미터를 &로 구분하여 사용할 수 있습니다.
  • 장점: 다양한 필터링 옵션을 추가하기에 적합합니다. 예를 들어, ?pCategory=aa&rating=5와 같이 여러 쿼리 파라미터를 추가하여 보다 세부적인 검색이 가능합니다.
  • 컨트롤러:
    java
    코드 복사
    @GetMapping public List<PlaceDto> getPlacesByCategory(@RequestParam("pCategory") String pCategory) { return placeService.findPlacesBypCategory(pCategory); }

2. 경로 변수 (/places/pCategory/{pCategory})

  • 사용 예: /places/pCategory/aa
  • 설명: 경로 변수는 URL 경로의 일부분으로, URL 패턴에서 중괄호 {}로 감싸진 부분입니다. 이 부분이 변수로 대체되어 해당 리소스를 식별합니다.
  • 장점: 리소스 식별에 적합하며, URL이 더 직관적입니다. 리소스의 계층 구조를 표현하는 데 유용합니다.
  • 컨트롤러:
    java
    코드 복사
    @GetMapping("/pCategory/{pCategory}") public List<PlaceDto> getPlacesByCategory(@PathVariable("pCategory") String pCategory) { return placeService.findPlacesBypCategory(pCategory); }

설계 및 선택 기준

  • 쿼리 파라미터는 필터링, 정렬, 페이징 등의 여러 추가 정보를 URL에 전달할 때 유용합니다. 예를 들어, 검색 조건이 복잡하거나 여러 조건을 조합할 때 사용합니다.
  • 경로 변수는 리소스의 계층 구조를 명확히 하고, RESTful API에서 리소스를 구별할 때 사용합니다.

예제 설명

  • /places?pCategory=aa는 pCategory라는 쿼리 파라미터를 사용하여, 카테고리에 따라 필터링된 장소들을 가져오는 API입니다.
  • /places/pCategory/aa는 경로에 pCategory 값을 포함하여, 해당 카테고리의 장소들을 가져오는 API입니다.

현재 설계하신 /places?pCategory=aa 방식이 다양한 필터링 옵션을 지원할 가능성이 높으며, RESTful API 디자인 원칙에 따라 @RequestParam을 사용하는 것이 더 일반적입니다.
따라서, 쿼리 파라미터를 사용하려면 @RequestParam을, 경로 변수를 사용하려면 @PathVariable을 활용하세요.
 

 

https://covenant.tistory.com/241