Skip to content

aip-124

TL;DR⚑

  • API 리소스 계층 구조는 단일 부모를 가져야 함.
  • 다대일 관계가 있는 경우 하나의 정식 부모를 선택해야 함.
  • 다대다 관계는 repeated 필드 또는 서브 리소스로 모델링할 수 있음.
  • 서브 리소스는 추가 메타데이터가 필요할 때만 사용해야 함.

리소스 계층 구조 원칙⚑

  • API의 각 리소스는 하나의 정식 부모만 가져야 함.
  • List 요청 시, 두 개 이상의 부모를 필요로 하지 않아야 함.
  • parent 필드는 필수(required) 필드로 지정해야 함.

다대일 관계 모델링⚑

  • 리소스가 여러 개의 부모를 가질 수 있는 경우, 단 하나의 정식 부모를 선택해야 함.
  • 다른 연관된 리소스는 추가 필드로 관리해야 함.
  • 예제:
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };

  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  string author = 2 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Author"
  }];
}

다대다 관계 모델링⚑

  • 기본적으로 repeated 필드를 사용하여 다대다 관계를 표현할 수 있음.
  • 예제:
message Book {
  option (google.api.resource) = {
    type: "library.googleapis.com/Book"
    pattern: "publishers/{publisher}/books/{book}"
  };

  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  repeated string authors = 2 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Author"
  }];
}

서브 리소스를 활용한 다대다 관계 모델링⚑

  • repeated 필드가 제한적이거나, 추가적인 메타데이터가 필요할 경우 서브 리소스를 사용할 수 있음.
  • 예제:
message BookAuthor {
  option (google.api.resource) = {
    type: "library.googleapis.com/BookAuthor"
    pattern: "publishers/{publisher}/books/{book}/authors/{book_author}"
  };

  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  string author = 2 [(google.api.resource_reference) = {
    type: "library.googleapis.com/Author"
  }];
}

정리⚑

  • 리소스 계층 구조는 단일 부모 원칙을 따라야 함.
  • 다대일 관계는 하나의 정식 부모를 설정하고, 다른 연관 관계는 추가 필드로 관리해야 함.
  • 다대다 관계는 repeated 필드 또는 서브 리소스를 활용할 수 있으며, 추가적인 메타데이터가 필요할 때만 서브 리소스를 사용해야 함.