자식 개체를 게시하고 모든 부모의 자식을 모두 가져 오기 위해 API 끝점을 디자인하는 방법은 무엇입니까?

예를 들어 클라이언트, 보고서 엔티티가 있습니다. 고객에게 많은 보고서가있을 수 있으며 단일 보고서 관리에 대한 끝 점이 다음과 같이 중첩되어야한다고 생각합니다.

/clients/{client_id}/reports/{report_id}

한 고객의 모든 보고서에 대해서는 다음과 같이 지적합니다.

/clients/{client_id}/reports

그러나 모든 클라이언트의 모든 보고서가 API를 일관되고 잘 설계되도록하기 위해 어떻게 엔드 포인트를 찾아야합니까?

내 접근 방식 :

(구글 구글 API에서 보았습니다) 대신 "-"를 사용하고 "all"로 구문 분석하십시오.

/clients/-/reports

이것은 엔드 포인트 형식을 동일하게 유지하지만 약간 쓸모가없는 것처럼 보이며이 방법을 제안하는 rfc를 찾을 수 없습니다.

모든 보고서에 대해서만 별도의 엔드 포인트를 작성하십시오.

/reports

그러나 고객 보고서를 얻으려면 여전히 다음과 같습니다.

/clients/{client_id}/reports

"클라이언트"를 부모가 아니라 필터 매개 변수로 만들기 위해 엔드 포인트를 리팩터링하십시오.

/reports?client={client_id} -한 고객의 보고서

/reports -모든 고객의 보고서

특정 클라이언트에 대한 보고서를 게시하기 위해 새 끝점을 추가하는 경우 URL에 매개 변수가있는 POST 요청이므로보기에 좋지 않을 수 있습니다.

아이디어에 대한 다른 제안이 있습니까?

rest api api-design

— 얀
소스

당신이 관심을 가질만한 질문

— LAIV

답변:

그러나 모든 클라이언트의 모든 보고서가 API를 일관되고 잘 설계되도록하기 위해 어떻게 엔드 포인트를 찾아야합니까?

무엇보다도 RESTful API 모델링을위한 황금률이 없다는 것을 기억하십시오. 우리가 가진 모든 것은 모범 사례와 규칙입니다. 즉, 평상시처럼 귀하의 요구 사항을 가장 잘 충족시키는 모델과이 경우 모델을 가장 잘 표현하는 답변을 선택하십시오.

따라서 표현력에서 세 가지 옵션을 확인하십시오.

# 1 "-"표기법

이것은 밝은 생각입니다. 그것은 우리 가 속한 모든reportsclients 조건을 표현할 수있게 합니다 . '쿼리'를 특정 보고서 세트 (범위 내에있는 보고서)로 좁 힙니다 clients.

그것은 항상 계층 구조의 개념을 유지하므로 reports다른 위치에서 찾을 수 있다면 이 표기법이 크게 도움이됩니다. 예를 들면 다음과 같습니다.

클라이언트에 속하는 모든 보고서 /clients/-/reports
부서에 속하는 모든 보고서 /departments/-/reports
직원에 속하는 모든 보고서 /employees/-/reports

그러나 시스템에서 사용 가능한 모든 보고서를 검색하기 위해 계층 구조를 유지한다고해서 다음 옵션에 비해 귀중한 이점을 제공하지는 않습니다.

# 2 다른 URI

사용 가능한 모든 보고서 를 검색 할 때 경계 / 컨텍스트 / 계층 구조 를 표현할 필요가없는 경우이 방법이 더 합리적입니다.

새로운 URI ( /reports)는 또한 보고서 관리 의 가능성을 열어 둡니다 . 그러나 필요하다고 생각하지 않으면 완전한 RESTful 지원을 제공 할 필요가 없습니다. 예를 들어을 언급했습니다 Make a separate endpoint just for all the reports. 괜찮습니다. 구현 GET하기 위해 필터 를 구현하면 되고 일부 필터 만 있으면됩니다 .

여전히이 작업을 수행 할 수 /reports?client={client_id}있습니다. 동일한 리소스에 다른 URI를 사용하는 것이 좋습니다. 내가 읽은 일부 기사는 이것을 견고 함 이라고 부릅니다 .

# 3 계층 구조 되돌리기

이 방법이 귀하의 기대를 충족시키지 못한다는 느낌을받습니다. 또한, 그것은 결국 시작점으로 당신을 가져올 것이라고 생각합니다.

결론

# 1과 # 2는 상호 배타적이지 않습니다. 둘 다 구현할 수 있습니다. 실제 상황과 OP의 전제에 따르면 # 2 만 구현할 것입니다.

^{1 : 그것은 /clients/-/reports내가 생각 하는 것과 같습니다}

— 레이브
소스

Google의 API 디자인 패턴은이 시나리오에서 '-'사용을 제안합니다.

GET /clients/-/reports

출처:

https://cloud.google.com/apis/design/design_patterns#list_sub-collections

— wfg4
소스

지금까지 내가 전능하신 구글에 동의하는 것이 될,하지만 난 뭔가를 선호하는 거라고 생각 /client/{client_id}/report/{report_id}하고/clients/report/{report_id}

— 로버트 하비

@RobertHarvey 왜 안돼 /reports?

— Laiv

@Laiv : 모든 보고서를 암시합니다. 페이지를 새로 고침하십시오. 닌자 편집을했습니다.

— Robert Harvey

@RobertHarvey I 평균, 왜 2 개의 다른 엔드 포인트 /clients...및 /reports.

— Laiv

@Laiv : 좋습니다.하지만 "요청 본문에 어떤 매개 변수를 넣어야합니까?"라는 질문 만 제기됩니다.

— Robert Harvey