// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.resourcemanager.v3;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/longrunning/operations.proto";

option csharp_namespace = "Google.Cloud.ResourceManager.V3";
option go_package = "google.golang.org/genproto/googleapis/cloud/resourcemanager/v3;resourcemanager";
option java_multiple_files = true;
option java_outer_classname = "TagBindingsProto";
option java_package = "com.google.cloud.resourcemanager.v3";
option php_namespace = "Google\\Cloud\\ResourceManager\\V3";
option ruby_package = "Google::Cloud::ResourceManager::V3";

// Allow users to create and manage TagBindings between TagValues and
// different cloud resources throughout the GCP resource hierarchy.
service TagBindings {
  option (google.api.default_host) = "cloudresourcemanager.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/cloud-platform.read-only";

  // Lists the TagBindings for the given cloud resource, as specified with
  // `parent`.
  //
  // NOTE: The `parent` field is expected to be a full resource name:
  // https://cloud.google.com/apis/design/resource_names#full_resource_name
  rpc ListTagBindings(ListTagBindingsRequest) returns (ListTagBindingsResponse) {
    option (google.api.http) = {
      get: "/v3/tagBindings"
    };
    option (google.api.method_signature) = "parent";
  }

  // Creates a TagBinding between a TagValue and a cloud resource
  // (currently project, folder, or organization).
  rpc CreateTagBinding(CreateTagBindingRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v3/tagBindings"
      body: "tag_binding"
    };
    option (google.api.method_signature) = "tag_binding";
    option (google.longrunning.operation_info) = {
      response_type: "TagBinding"
      metadata_type: "CreateTagBindingMetadata"
    };
  }

  // Deletes a TagBinding.
  rpc DeleteTagBinding(DeleteTagBindingRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v3/{name=tagBindings/**}"
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "google.protobuf.Empty"
      metadata_type: "DeleteTagBindingMetadata"
    };
  }
}

// A TagBinding represents a connection between a TagValue and a cloud
// resource (currently project, folder, or organization). Once a TagBinding is
// created, the TagValue is applied to all the descendants of the cloud
// resource.
message TagBinding {
  option (google.api.resource) = {
    type: "cloudresourcemanager.googleapis.com/TagBinding"
    pattern: "tagBindings/{tag_binding}"
  };

  // Output only. The name of the TagBinding. This is a String of the form:
  // `tagBindings/{full-resource-name}/{tag-value-name}` (e.g.
  // `tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F123/tagValues/456`).
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The full resource name of the resource the TagValue is bound to.
  // E.g. `//cloudresourcemanager.googleapis.com/projects/123`
  string parent = 2;

  // The TagValue of the TagBinding.
  // Must be of the form `tagValues/456`.
  string tag_value = 3;
}

// Runtime operation information for creating a TagValue.
message CreateTagBindingMetadata {

}

// The request message to create a TagBinding.
message CreateTagBindingRequest {
  // Required. The TagBinding to be created.
  TagBinding tag_binding = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Set to true to perform the validations necessary for creating the resource,
  // but not actually perform the action.
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Runtime operation information for deleting a TagBinding.
message DeleteTagBindingMetadata {

}

// The request message to delete a TagBinding.
message DeleteTagBindingRequest {
  // Required. The name of the TagBinding. This is a String of the form:
  // `tagBindings/{id}` (e.g.
  // `tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F123/tagValues/456`).
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/TagBinding"
    }
  ];
}

// The request message to list all TagBindings for a parent.
message ListTagBindingsRequest {
  // Required. The full resource name of a resource for which you want to list existing
  // TagBindings.
  // E.g. "//cloudresourcemanager.googleapis.com/projects/123"
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "*"
    }
  ];

  // Optional. The maximum number of TagBindings to return in the response. The server
  // allows a maximum of 300 TagBindings to return. If unspecified, the server
  // will use 100 as the default.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A pagination token returned from a previous call to `ListTagBindings`
  // that indicates where this listing should continue from.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// The ListTagBindings response.
message ListTagBindingsResponse {
  // A possibly paginated list of TagBindings for the specified TagValue or
  // resource.
  repeated TagBinding tag_bindings = 1;

  // Pagination token.
  //
  // If the result set is too large to fit in a single response, this token
  // is returned. It encodes the position of the current result cursor.
  // Feeding this value into a new list request with the `page_token` parameter
  // gives the next page of the results.
  //
  // When `next_page_token` is not filled in, there is no next page and
  // the list returned is the last page in the result set.
  //
  // Pagination tokens have a limited lifetime.
  string next_page_token = 2;
}
