blob: 1f668f73a5d642ff499949397dfe144ea0cf5eba [file] [log] [blame]
// Copyright 2020 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file or at
// https://developers.google.com/open-source/licenses/bsd
syntax = "proto3";
package monorail.v3;
option go_package = "api/v3/api_proto";
import "api/v3/api_proto/feature_objects.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/empty.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
// ***ONLY CALL rpcs WITH `status: {ALPHA|STABLE}`***
// rpcs without `status` are not ready.
// Hotlists service includes all methods needed for managing Hotlists.
service Hotlists {
// status: NOT READY
// Creates a new hotlist.
//
// Raises:
// NOT_FOUND if some given hotlist editors do not exist.
// ALREADY_EXISTS if a hotlist with the same name owned by the user
// already exists.
// INVALID_ARGUMENT if a `hotlist.owner` is given.
rpc CreateHotlist (CreateHotlistRequest) returns (Hotlist) {}
// status: NOT READY
// Returns the requested Hotlist.
//
// Raises:
// NOT_FOUND if the requested hotlist is not found.
// PERMISSION_DENIED if the requester is not allowed to view the hotlist.
// INVALID_ARGUMENT if the given resource name is not valid.
rpc GetHotlist (GetHotlistRequest) returns (Hotlist) {}
// status: NOT READY
// Updates a hotlist.
//
// Raises:
// NOT_FOUND if the hotlist is not found.
// PERMISSION_DENIED if the requester is not allowed to update the hotlist.
// INVALID_ARGUMENT if required fields are missing.
rpc UpdateHotlist (UpdateHotlistRequest) returns (Hotlist) {}
// status: NOT READY
// Deletes a hotlist.
//
// Raises:
// NOT_FOUND if the hotlist is not found.
// PERMISSION_DENIED if the requester is not allowed to delete the hotlist.
rpc DeleteHotlist (GetHotlistRequest) returns (google.protobuf.Empty) {}
// status: NOT READY
// Returns a list of all HotlistItems in the hotlist.
//
// Raises:
// NOT_FOUND if the parent hotlist is not found.
// PERMISSION_DENIED if the requester is not allowed to view the hotlist.
// INVALID_ARGUMENT if the page_token or given hotlist resource name is not
// valid.
rpc ListHotlistItems (ListHotlistItemsRequest) returns (ListHotlistItemsResponse) {}
// status: NOT READY
// Reranks a hotlist's items.
//
// Raises:
// NOT_FOUND if the hotlist or issues to rerank are not found.
// PERMISSION_DENIED if the requester is not allowed to rerank the hotlist
// or view issues they're trying to rerank.
// INVALID_ARGUMENT if the `target_position` is invalid or `hotlist_items`
// is empty or contains items not in the Hotlist.
rpc RerankHotlistItems (RerankHotlistItemsRequest) returns (google.protobuf.Empty) {}
// status: NOT READY
// Adds new items associated with given issues to a hotlist.
//
// Raises:
// NOT_FOUND if the parent hotlist or issues are not found.
// PERMISSION_DENIED if the requester is not allowed to edit the hotlist or
// view issues they are trying to add.
// INVALID_ARGUMENT if the `target_position` is invalid or `hotlist_items`
// is empty or contains items not in the Hotlist.
rpc AddHotlistItems (AddHotlistItemsRequest) returns (google.protobuf.Empty) {}
// status: NOT READY
// Removes items associated with given issues from a hotlist.
//
// Raises:
// NOT_FOUND if the parent hotlist or issues are not found.
// PERMISSION_DENIED if the requester is not allowed to edit the hotlist or
// view issues they are trying to remove.
// INVALID_ARGUMENT if the `target_position` is invalid or `hotlist_items`
// is empty or contains items not in the Hotlist.
rpc RemoveHotlistItems (RemoveHotlistItemsRequest) returns (google.protobuf.Empty) {}
// status: NOT READY
// Removes editors assigned to a hotlist.
//
// Raises:
// NOT_FOUND if the hotlist is not found.
// PERMISSION_DENIED if the requester is not allowed to remove all specified
// editors from the hotlist.
// INVALID_ARGUMENT if any specified editors are not in the hotlist.
rpc RemoveHotlistEditors (RemoveHotlistEditorsRequest) returns (google.protobuf.Empty) {}
// status: NOT READY
// Gathers all viewable hotlists that a user is a member of.
//
// Raises:
// NOT_FOUND if the user is not found.
// INVALID_ARGUMENT if the `user` is invalid.
rpc GatherHotlistsForUser (GatherHotlistsForUserRequest) returns (GatherHotlistsForUserResponse) {}
}
// Request message for CreateHotlist method.
// Next available tag: 2
message CreateHotlistRequest {
// The hotlist to create.
// `hotlist.owner` must be empty. The owner of the new hotlist will be
// set to the requester.
Hotlist hotlist = 1 [ (google.api.field_behavior) = REQUIRED ];
}
// Request message for GetHotlist method.
// Next available tag: 2
message GetHotlistRequest {
// The name of the hotlist to retrieve.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/Hotlist"}];
}
// Request message for UpdateHotlist method.
// Next available tag: 2
message UpdateHotlistRequest {
// The hotlist's `name` field is used to identify the hotlist to be updated.
Hotlist hotlist = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
// The list of fields to be updated.
google.protobuf.FieldMask update_mask = 2 [ (google.api.field_behavior) = REQUIRED ];
}
// Request message for ListHotlistItems method.
// Next available tag: 5
message ListHotlistItemsRequest {
// The parent hotlist, which owns this collection of items.
string parent = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
// The maximum number of items to return. The service may return fewer than
// this value.
// If unspecified, at most 1000 items will be returned.
// The maximum value is 1000; values above 1000 will be coerced to 1000.
int32 page_size = 2;
// The string of comma separated field names used to order the items.
// Adding '-' before a field, reverses the sort order.
// E.g. 'stars,-status' sorts the items by number of stars low to high, then
// status high to low.
// If unspecified, items will be ordered by their rank in the parent.
string order_by = 3;
// A page token, received from a previous `ListHotlistItems` call.
// Provide this to retrieve the subsequent page.
//
// When paginating, all other parameters provided to `ListHotlistItems` must
// match the call that provided the page token.
string page_token = 4;
}
// Response to ListHotlistItems call.
// Next available tag: 3
message ListHotlistItemsResponse {
// The items from the specified hotlist.
repeated HotlistItem items = 1;
// A token, which can be sent as `page_token` to retrieve the next page.
// If this field is omitted, there are no subsequent pages.
string next_page_token = 2;
}
// The request used to rerank a Hotlist.
// Next available tag: 4
message RerankHotlistItemsRequest {
// Resource name of the Hotlist to rerank.
string name = 1 [
(google.api.resource_reference) = {type: "api.crbug.com/Hotlist"},
(google.api.field_behavior) = REQUIRED ];
// HotlistItems to be moved. The order of `hotlist_items` will
// determine the order of these items after they have been moved.
// E.g. With items [a, b, c, d, e], moving [d, c] to `target_position` 3, will
// result in items [a, b, e, d, c].
repeated string hotlist_items = 2 [
(google.api.resource_reference) = {type: "api.crbug.com/HotlistItem"},
(google.api.field_behavior) = REQUIRED ];
// Target starting position of the moved items.
// `target_position` must be between 0 and (# hotlist items - # items being moved).
uint32 target_position = 3 [ (google.api.field_behavior) = REQUIRED ];
}
// Request message for an AddHotlistItems call.
// Next available tag: 4
message AddHotlistItemsRequest {
// Resource name of the Hotlist to add new items to.
string parent = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
// Resource names of Issues to associate with new HotlistItems added to `parent`.
repeated string issues = 2 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/Issue"} ];
// Target starting position of the new items.
// `target_position` must be between [0 and # of items that currently exist in
// `parent`]. The request will fail if a specified `target_position` is outside
// of this range.
// New HotlistItems added to a non-last position of the hotlist will
// cause ranks of existing HotlistItems below `target_position` to be adjusted.
// If no `target_position` is given, new items will be added to the end of
// `parent`.
uint32 target_position = 3;
}
// Request message for a RemoveHotlistItems call.
// Next available tag: 3
message RemoveHotlistItemsRequest {
// Resource name of the Hotlist to remove items from.
string parent = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
// Resource names of Issues associated with HotlistItems that should be removed.
repeated string issues = 2 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/Issue"} ];
}
// Request message for a RemoveHotlistEditors call.
// Next available tag: 3
message RemoveHotlistEditorsRequest {
// Resource name of the Hotlist to remove editors from.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
// Resource names of Users associated with the hotlist that should be removed.
repeated string editors = 2 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/User"} ];
}
// Request message for a GatherHotlistsForUser call.
// Next available tag: 2
message GatherHotlistsForUserRequest {
// Resource name of the user whose hotlists we want to fetch.
string user = 1 [ (google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {type: "api.crbug.com/User"} ];
}
// Response message for a GatherHotlistsForUser call.
// Next available tag: 2
message GatherHotlistsForUserResponse {
repeated Hotlist hotlists = 1;
}