my_festival_service.proto

// Online "my festival" API: shared rating and recommendation aggregates.
syntax = "proto3";

package cambeerfestival.myfestival.v1;

import "cambeerfestival/myfestival/v1/rating.proto";
import "cambeerfestival/myfestival/v1/recommendation.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

// Stores each device's rating / "would recommend" answer for a drink and
// serves back the bucket-scoped aggregate. Writes are local-first on the
// client; this service is the shared, cross-device aggregate.
service MyFestivalService {
  option (google.api.default_host) = "data.cambeerfestival.app";

  // --- Ratings -------------------------------------------------------------

  // Get this device's rating for a drink.
  rpc GetRating(GetRatingRequest) returns (Rating) {
    option (google.api.http) = {get: "/v1/{name=festivals/*/drinks/*/ratings/*}"};
    option (google.api.method_signature) = "name";
  }

  // Create or update this device's rating for a drink (upsert).
  rpc UpdateRating(UpdateRatingRequest) returns (Rating) {
    option (google.api.http) = {
      patch: "/v1/{rating.name=festivals/*/drinks/*/ratings/*}"
      body: "rating"
    };
    option (google.api.method_signature) = "rating,update_mask";
  }

  // Remove this device's rating for a drink.
  rpc DeleteRating(DeleteRatingRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {delete: "/v1/{name=festivals/*/drinks/*/ratings/*}"};
    option (google.api.method_signature) = "name";
  }

  // Get the aggregate rating for a single drink.
  rpc GetRatingSummary(GetRatingSummaryRequest) returns (RatingSummary) {
    option (google.api.http) = {get: "/v1/{name=festivals/*/ratingSummaries/*}"};
    option (google.api.method_signature) = "name";
  }

  // List aggregate ratings for every rated drink at a festival.
  rpc ListRatingSummaries(ListRatingSummariesRequest) returns (ListRatingSummariesResponse) {
    option (google.api.http) = {get: "/v1/{parent=festivals/*}/ratingSummaries"};
    option (google.api.method_signature) = "parent";
  }

  // --- Recommendations -----------------------------------------------------

  // Get this device's "would recommend" answer for a drink.
  rpc GetRecommendation(GetRecommendationRequest) returns (Recommendation) {
    option (google.api.http) = {get: "/v1/{name=festivals/*/drinks/*/recommendations/*}"};
    option (google.api.method_signature) = "name";
  }

  // Create or update this device's "would recommend" answer (upsert).
  rpc UpdateRecommendation(UpdateRecommendationRequest) returns (Recommendation) {
    option (google.api.http) = {
      patch: "/v1/{recommendation.name=festivals/*/drinks/*/recommendations/*}"
      body: "recommendation"
    };
    option (google.api.method_signature) = "recommendation,update_mask";
  }

  // Remove this device's "would recommend" answer for a drink.
  rpc DeleteRecommendation(DeleteRecommendationRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {delete: "/v1/{name=festivals/*/drinks/*/recommendations/*}"};
    option (google.api.method_signature) = "name";
  }

  // Get the aggregate recommendation for a single drink.
  rpc GetRecommendationSummary(GetRecommendationSummaryRequest) returns (RecommendationSummary) {
    option (google.api.http) = {get: "/v1/{name=festivals/*/recommendationSummaries/*}"};
    option (google.api.method_signature) = "name";
  }

  // List aggregate recommendations for every drink with an answer.
  rpc ListRecommendationSummaries(ListRecommendationSummariesRequest) returns (ListRecommendationSummariesResponse) {
    option (google.api.http) = {get: "/v1/{parent=festivals/*}/recommendationSummaries"};
    option (google.api.method_signature) = "parent";
  }
}

// --- Rating requests -------------------------------------------------------

message GetRatingRequest {
  // Resource name: festivals/{festival}/drinks/{drink}/ratings/{device}.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "myfestival.cambeerfestival.app/Rating"
  ];
}

message UpdateRatingRequest {
  // The rating to set. Its `name` identifies the resource.
  Rating rating = 1 [(google.api.field_behavior) = REQUIRED];

  // Fields to update; omit to update all populated fields.
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = OPTIONAL];

  // If true (the default for this API), create the rating when absent (upsert).
  bool allow_missing = 3 [(google.api.field_behavior) = OPTIONAL];
}

message DeleteRatingRequest {
  // Resource name: festivals/{festival}/drinks/{drink}/ratings/{device}.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "myfestival.cambeerfestival.app/Rating"
  ];
}

message GetRatingSummaryRequest {
  // Resource name: festivals/{festival}/ratingSummaries/{drink}.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "myfestival.cambeerfestival.app/RatingSummary"
  ];
}

message ListRatingSummariesRequest {
  // Parent festival: festivals/{festival}.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).child_type = "myfestival.cambeerfestival.app/RatingSummary"
  ];

  // Maximum number to return; the server may return fewer. Defaults applied
  // when unset or zero.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Page token from a previous response.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

message ListRatingSummariesResponse {
  // Aggregate ratings for this page, one per rated drink.
  repeated RatingSummary rating_summaries = 1;

  // Token for the next page; empty when there are no more.
  string next_page_token = 2;

  // Total number of rated drinks at the festival.
  int32 total_size = 3;
}

// --- Recommendation requests -----------------------------------------------

message GetRecommendationRequest {
  // festivals/{festival}/drinks/{drink}/recommendations/{device}.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "myfestival.cambeerfestival.app/Recommendation"
  ];
}

message UpdateRecommendationRequest {
  // The answer to set. Its `name` identifies the resource.
  Recommendation recommendation = 1 [(google.api.field_behavior) = REQUIRED];

  // Fields to update; omit to update all populated fields.
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = OPTIONAL];

  // If true (the default for this API), create the answer when absent (upsert).
  bool allow_missing = 3 [(google.api.field_behavior) = OPTIONAL];
}

message DeleteRecommendationRequest {
  // festivals/{festival}/drinks/{drink}/recommendations/{device}.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "myfestival.cambeerfestival.app/Recommendation"
  ];
}

message GetRecommendationSummaryRequest {
  // festivals/{festival}/recommendationSummaries/{drink}.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "myfestival.cambeerfestival.app/RecommendationSummary"
  ];
}

message ListRecommendationSummariesRequest {
  // Parent festival: festivals/{festival}.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).child_type = "myfestival.cambeerfestival.app/RecommendationSummary"
  ];

  // Maximum number to return; the server may return fewer.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Page token from a previous response.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

message ListRecommendationSummariesResponse {
  // Aggregate recommendations for this page, one per drink with an answer.
  repeated RecommendationSummary recommendation_summaries = 1;

  // Token for the next page; empty when there are no more.
  string next_page_token = 2;

  // Total number of drinks with at least one answer.
  int32 total_size = 3;
}