RESTful API를 매우 예측 가능하게 만들고 싶습니다. 쿼리 매개 변수를 사용하지 않고 URI를 사용하여 데이터를 분할 할시기를 결정하는 가장 좋은 방법은 무엇입니까?
페이지 매김, 정렬 및 그룹화를 지원하는 시스템 매개 변수는 '?'다음에 오는 것이 좋습니다. 그러나 '상태'및 '지역'또는 컬렉션을 분류하는 다른 속성과 같은 필드는 어떻습니까? 이것들이 쿼리 매개 변수가되어야한다면, 경로 매개 변수를 언제 사용 해야하는지 아는 규칙은 무엇입니까?
답변:
RESTful API 설계의 모범 사례는 경로 매개 변수를 사용하여 특정 자원을 식별하고 쿼리 매개 변수를 사용하여 해당 자원을 정렬 / 필터링하는 것입니다.
다음은 예입니다. Car라는 엔티티에 RESTful API 엔드 포인트를 구현한다고 가정하십시오. 엔드 포인트를 다음과 같이 구성하십시오.
GET /cars
GET /cars/:id
POST가 /cars
PUT /cars/:id
DELETE/cars/:id
이렇게하면 가져올 리소스를 지정할 때 경로 매개 변수 만 사용하지만 어떤 식 으로든 리소스를 정렬 / 필터링하지는 않습니다.
이제 GET 요청에서 자동차를 색상별로 필터링하는 기능을 추가하려고한다고 가정하십시오. 색상은 리소스가 아니므로 (리소스의 속성)이를 수행하는 쿼리 매개 변수를 추가 할 수 있습니다. 다음 과 같이 해당 검색어 매개 변수를 GET/cars 요청에 추가합니다 .
가져 오기 /cars?color=blue
이 엔드 포인트는 파란색 자동차 만 반환되도록 구현됩니다.
구문과 관련하여 URL 이름은 모두 소문자 여야합니다. 일반적으로 영어로 두 단어로 된 엔티티 이름이 있으면 낙타 대소 문자가 아닌 하이픈을 사용하여 단어를 구분합니다.
전의. /two-words
이 주제에 대해 생각하는 기본 방법은 다음과 같습니다.
URI는 리소스 TYPE의 특정 인스턴스를 고유하게 식별하는 리소스 식별자입니다. 인생의 다른 모든 것들과 마찬가지로, 모든 객체 (일부 유형의 인스턴스)는 시간에 따라 변하거나 일시적인 속성 집합을 갖습니다.
위의 예에서 자동차는 절대 변하지 않는 제조사, 모델 및 VIN과 같은 속성과 시간에 따라 변할 수있는 색상, 서스펜션 등을 갖는 매우 실질적인 객체입니다. 따라서 시간이 지남에 따라 변경 될 수있는 속성 (일시적)으로 URI를 인코딩하면 동일한 객체에 대해 여러 개의 URI가 생길 수 있습니다.
GET /cars/honda/civic/coupe/{vin}/{color=red}그리고 몇 년 후,이 자동차의 색상이 검은 색으로 바뀌면 :
GET /cars/honda/civic/coupe/{vin}/{color=black}자동차 인스턴스 자체 (객체)는 변경되지 않았습니다. 변경된 색상 일뿐입니다. 동일한 객체 인스턴스를 가리키는 여러 개의 URI를 사용하면 여러 개의 URI 핸들러를 작성해야합니다. 이는 효율적인 설계가 아니며 당연하지도 않습니다.
따라서 URI는 변경되지 않으며 수명 동안 해당 리소스를 고유하게 계속 식별하는 부분으로 만 구성되어야합니다. 변경 될 수있는 모든 것은 다음과 같이 쿼리 매개 변수를 위해 예약되어야합니다.
GET /cars/honda/civic/coupe/{vin}?color={black}결론-다형성을 생각하십시오.
REST API에서는 예측 가능한 URI에 지나치게 신경을 쓰지 않아야합니다. URI 예측 가능성에 대한 제안은 RESTful 아키텍처에 대한 오해를 암시합니다. 클라이언트는 URI 자체를 구성해야한다고 가정합니다. URI는 실제로 필요하지 않습니다.
그러나 귀하는 진정한 REST API가 아니라 'REST에서 영감을 얻은'API (예 : Google 드라이브 API)를 생성한다고 가정합니다. 이러한 경우 경험의 규칙은 '경로 매개 변수 = 자원 식별'및 '쿼리 매개 변수 = 자원 정렬'입니다. 따라서 질문은 상태 / 지역없이 자원을 고유하게 식별 할 수 있습니까? 그렇다면 쿼리 매개 변수 일 수 있습니다. 아니라면 경로 매개 변수입니다.
HTH.
일단 내가 주된 리소스 인 API를 디자인했다 people. 일반적으로 사용자는 필터링을 요청하여 사용자가 매번 people같은 것을 호출하지 않도록 나중에 나중에 쉽게 추가 할 수 있도록 /people?settlement=urban구현했습니다 . 또한 나중에 사용할 경우 전체 목록 에 액세스 할 수 있습니다. 요컨대, 내 추론은 일반적인 하위 집합에 경로를 추가하는 것이 었습니다/people/urban/people/rural/people
에서 여기 :
일반적인 검색어에 대한 별칭
일반 소비자에게 API 환경을보다 즐겁게하려면 조건 세트를 쉽게 액세스 할 수있는 RESTful 경로로 패키징하는 것이 좋습니다. 예를 들어, 최근에 마감 된 티켓 쿼리는 다음과 같이 패키지 될 수 있습니다.
GET /tickets/recently_closed
세분화는 더 계층 적이며 "예쁜"이지만 제한적일 수 있습니다.
예를 들어, 세 개의 세그먼트가있는 URL이있는 경우 각각 하나는 다른 매개 변수를 전달하여 제조업체, 모델 및 색상을 통해 자동차를 검색합니다.
www.example.com/search/honda/civic/blue이것은 매우 예쁜 URL이며 최종 사용자가 더 쉽게 기억할 수 있지만 이제는이 구조에 붙어 있습니다. 검색에서 사용자가 모든 파란 차 또는 모든 혼다 시빅을 검색 할 수 있도록하려면? 쿼리 매개 변수는 키 값 쌍을 제공하므로이 문제를 해결합니다. 그래서 당신은 전달할 수 있습니다 :
www.example.com/search?color=blue
www.example.com/search?make=civic이제 쿼리 코드에서 "color"또는 "make"키를 통해 값을 참조 할 수 있습니다.
더 많은 세그먼트를 사용하여 다음과 같은 종류의 키 값 구조를 만들면이 문제를 해결할 수 있습니다.
www.example.com/search/make/honda/model/civic/color/blue이해가 되길 바랍니다 ..