Rest-API 작명

안녕하세요, 이도원입니다.

문의하신 내용은 REST API 설계에 관련 된 부분인 것 같습니다.

GET /v1/admin/restaurants/search 이 방식과 GET /v1/restaurants/가게 이름

말씀하신 내용처럼, 위 2개의 URI 서로 같은 레벨에서의 endpoint라고 보기 어렵기 때문에, 어떤 것이 더 좋다가 하기가 곤란할 것 같습니다. 작성해 주신 주소 그대로 해석해 보면,

• GET /v1/admin/restaurants/search-> restaurants를 검색하는 API

• GET /v1/restaurants/가게 이름-> restaurants 데이터 중 "가게 이름"에 해당 하는 정보를 요청하는 API

로 해석 될 수 있습니다. 요약하면, 검색과 상세보기에 해당하는 API(endpoint)라고 보여집니다.

GET을 이용하여, 검색이나 목록/상세 정보 보기 등의 API를 작성하려면, 해당하는 데이터의 리소스 전체를 나타낼 수 있는 복수형의 명사를 사용하면 전체 목록 보기가, 전체목록보기 뒤에, 리소스를 유일하게 구분 지을 수 있는 Unique한 Key(or ID) 정보가 붙으면 상세 보기로 구분 지으면 좋을 것 같습니다. 예를 들어,

// 전체 매장 조회 GET /v1/admin/restaurants

// 매장 상세 조회 GET /v1/admin/restaurants/rst00001

추가로, GET과 POST 이외에도 PUT, DELETE, PATCH 등의 HTTP Method를 같이 사용하시면 더 간략하고 명료하게 API를 설계 하실 수 있다고 생각됩니다.

추가 질문 사항 있으시면 글 남겨 주세요.

감사합니다.

안녕하세요, 인프런 AI 인턴입니다.

황중석님의 질문과 관련하여 RESTful API 설계에 대해 알고 싶으신 것 같습니다. REST API 설계 시 주소 작명과 관련한 규칙과 베스트 프랙티스를 이해하시려면 HTTP 메소드와 URI의 적절한 사용이 중요합니다.

주어진 예시에서 GET /v1/admin/restaurants/search와 GET /v1/restaurants/가게 이름 두 방식은 RESTful API 설계 관점에서 다른 의미를 지니고 있습니다.

1. GET /v1/admin/restaurants/search: 특정 검색 기능을 수행하기 위해 search라는 특별한 경로를 사용하는 방식입니다. 이 방식은 검색 기능에 대한 명시적인 URI를 제공하는 방식인데, 대개는 쿼리 스트링을 사용하여 필터링을 진행하는 것이 REST 원칙에 더 가깝습니다. 예: GET /v1/admin/restaurants?name=가게이름

2. GET /v1/restaurants/가게 이름: URI의 경로 부분에 검색하려는 가게 이름을 직접 포함시킨 방식입니다. 이는 URI에 동적 파라미터(Dynamic Parameter)를 사용하는 경우이며, 주로 리소스의 ID나 식별 가능한 고유값으로 사용합니다.

REST API 설계에서 일반적으로 권장하는 방식은 리소스를 명확하게 식별 가능한 경로와 쿼리 스트링을 통하여 필터링 조건을 제공하는 것입니다. 검색 기능의 경우 쿼리 스트링을 사용하여 GET /v1/admin/restaurants?name=가게이름 형식으로 작성하는 것이 좋습니다.

REST API 질문이 있습니다~
해당 링크에서는 REST API가 JSON 형식으로 데이터를 반환해야 하는지, @RestController와 @Controller의 차이에 대해 설명하고 있습니다.

간단한 질문 하나드리겠습니다.
이 곳에서는 같은 URL 경로에 대해 다른 HTTP 메소드(GET, POST, PUT)를 사용해 다양한 액션을 수행하는 것에 대한 이점에 대해 논하고 있습니다.

Restful api 검색 조건 설계 시 uri 를 어떻게 해야 할까요?
여기에서는 REST API에서 검색 조건에 대한 URI 설계 방법에 대해 설명하고 있습니다.

이러한 내용을 바탕으로 REST API 설계에 대해 더 깊이 있게 이해할 수 있으시길 바랍니다.

저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다.
현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏
추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.