// Copyright 2018 The Kubeflow Authors
//
// 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";

option go_package = "github.com/kubeflow/pipelines/backend/api/v2beta1/go_client";
package kubeflow.pipelines.backend.api.v2beta1;

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";
import "google/rpc/status.proto";
import "protoc-gen-swagger/options/annotations.proto";

option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
  responses: {
    key: "default";
    value: {
      schema: {
        json_schema: {
          ref: ".google.rpc.Status";
        }
      }
    }
  }
  // Use bearer token for authorizing access to job service.
  // Kubernetes client library(https://kubernetes.io/docs/reference/using-api/client-libraries/)
  // uses bearer token as default for authorization. The section below
  // ensures security definition object is generated in the swagger definition.
  // For more details see https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#securityDefinitionsObject
  security_definitions: {
    security: {
      key: "Bearer";
      value: {
        type: TYPE_API_KEY;
        in: IN_HEADER;
        name: "authorization";
      }
    }
  }
  security: {
    security_requirement: {
      key: "Bearer";
      value: {};
    }
  }
};

service PipelineService {
  // Creates a pipeline.
  rpc CreatePipeline(CreatePipelineRequest) returns (Pipeline) {
    option (google.api.http) = {
      post: "/apis/v2beta1/pipelines"
      body: "pipeline"
    };
  }

  // Finds a specific pipeline by ID.
  rpc GetPipeline(GetPipelineRequest) returns (Pipeline) {
    option (google.api.http) = {
      get: "/apis/v2beta1/pipelines/{pipeline_id}"
    };
  }

  // Finds a specific pipeline by name and namespace.
  rpc GetPipelineByName(GetPipelineByNameRequest) returns (Pipeline) {
    option (google.api.http) = {
      get: "/apis/v2beta1/pipelines/names/{name}"
    };
  }

  // Finds all pipelines within a namespace.
  rpc ListPipelines(ListPipelinesRequest) returns (ListPipelinesResponse) {
    option (google.api.http) = {
      get: "/apis/v2beta1/pipelines"
    };
  }

  // Deletes an empty pipeline by ID. Returns error if the pipeline has pipeline versions.
  rpc DeletePipeline(DeletePipelineRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/apis/v2beta1/pipelines/{pipeline_id}"
    };
  }

  // Creates a new pipeline and a new pipeline version in a single transaction.
  rpc CreatePipelineAndVersion(CreatePipelineAndVersionRequest) returns (Pipeline) {
    option (google.api.http) = {
      post: "/apis/v2beta1/pipelines/create"
      body: "*"
    };
  }

  // Adds a pipeline version to the specified pipeline ID.
  rpc CreatePipelineVersion(CreatePipelineVersionRequest)
      returns (PipelineVersion) {
    option (google.api.http) = {
      post: "/apis/v2beta1/pipelines/{pipeline_id}/versions"
      body: "pipeline_version"
    };
  }

  // Gets a pipeline version by pipeline version ID and pipeline ID.
  rpc GetPipelineVersion(GetPipelineVersionRequest) returns (PipelineVersion) {
    option (google.api.http) = {
      get: "/apis/v2beta1/pipelines/{pipeline_id}/versions/{pipeline_version_id}"
    };
  }

  // Lists all pipeline versions of a given pipeline ID.
  rpc ListPipelineVersions(ListPipelineVersionsRequest)
      returns (ListPipelineVersionsResponse) {
    option (google.api.http) = {
      get: "/apis/v2beta1/pipelines/{pipeline_id}/versions"
    };
  }

  // Deletes a specific pipeline version by pipeline version ID and pipeline ID.
  rpc DeletePipelineVersion(DeletePipelineVersionRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/apis/v2beta1/pipelines/{pipeline_id}/versions/{pipeline_version_id}"
    };
  }
}

message Pipeline {
  // Output. Unique pipeline ID. Generated by API server.
  string pipeline_id = 1;

  // Required input field. Pipeline name provided by user.
  string display_name = 2;

  // Optional input field. A short description of the pipeline.
  string description = 3;

  // Output. Creation time of the pipeline.
  google.protobuf.Timestamp created_at = 4;

  // Input. A namespace this pipeline belongs to.
  // Causes error if user is not authorized to access the specified namespace.
  // If not specified in CreatePipeline, default namespace is used.
  string namespace = 5;

  // In case any error happens retrieving a pipeline field, only pipeline ID,
  // and the error message is returned. Client has the flexibility of choosing
  // how to handle the error. This is especially useful during listing call.
  google.rpc.Status error = 6;
}

message PipelineVersion {
  // Required input field. Unique ID of the parent pipeline.
  // This is ignored in CreatePipelineAndVersion API.
  string pipeline_id = 1;

  // Output. Unique pipeline version ID. Generated by API server.
  string pipeline_version_id = 2;

  // Required input field. Pipeline version name provided by user.
  // This is ignored in CreatePipelineAndVersion API.
  string display_name = 3;

  // Optional input field. Short description of the pipeline version.
  // This is ignored in CreatePipelineAndVersion API.
  string description = 4;

  // Output. Creation time of the pipeline version.
  google.protobuf.Timestamp created_at = 5;

  // Input. Required. The URL to the source of the pipeline version.
  // This is required when creating the pipeine version through
  // CreatePipelineVersion or CreatePipelineAndVersion API.
  Url package_url = 6;

  // Input. Optional. The URL to the code source of the pipeline version.
  // The code is usually the Python definition of the pipeline and potentially
  // related the component definitions. This allows users to trace back to how
  // the pipeline YAML was created.
  string code_source_url = 9;

  // Output. The pipeline spec for the pipeline version.
  google.protobuf.Struct pipeline_spec = 7;
    
  // In case any error happens retrieving a pipeline version field, only
  // pipeline ID, pipeline version ID, and the error message are returned. 
  // Client has the flexibility of choosing how to handle the error. 
  // This is especially useful during List() calls.
  google.rpc.Status error = 8;
}

message Url {
  // URL of the pipeline version definition.
  string pipeline_url = 1;
}

message CreatePipelineRequest {
  // Required input. Pipeline that needs to be created.
  Pipeline pipeline = 1;
}

message GetPipelineRequest {
  // Required input. The ID of the pipeline to be retrieved.
  string pipeline_id = 1;
}

message ListPipelinesRequest {
  // Optional input. Namespace for the pipelines.
  string namespace = 1;

  // A page token to request the results page.
  string page_token = 2;

  // The number of pipelines to be listed per page. If there are more pipelines
  // than this number, the response message will contain a valid value in the
  // nextPageToken field.
  int32 page_size = 3;

  // Sorting order in form of "field_name", "field_name asc" or "field_name desc".
  // Ascending by default.
  string sort_by = 4;

  // A url-encoded, JSON-serialized filter protocol buffer (see
  // [filter.proto](https://github.com/kubeflow/pipelines/blob/master/backend/api/filter.proto)).
  string filter = 5;
}

message ListPipelinesResponse {
  // Returned pipelines.
  repeated Pipeline pipelines = 1;

  // The total number of pipelines for the given query.
  int32 total_size = 2;

  // The token to list the next page of pipelines.
  // This token can be used on the next ListPipelinesRequest.
  string next_page_token = 3;
}

message GetPipelineByNameRequest {
  // Optional input. Namespace of the pipeline. 
  // It could be empty if default namespaces needs to be used or if multi-user 
  // support is turned off.
  string namespace = 1;

  // Required input. Name of the pipeline to be retrieved.
  string name = 2;
}

message DeletePipelineRequest {
  // Required input. ID of the pipeline to be deleted.
  string pipeline_id = 1;
}

message CreatePipelineAndVersionRequest {
  // Required input. Pipeline (parent) to be created.
  Pipeline pipeline = 1;

  // Required input. Pipeline version (child) to be created.
  // Pipeline spec will be downloaded from pipeline_version.package_url.
  PipelineVersion pipeline_version = 2;
}

message CreatePipelineVersionRequest {
  // Required input. ID of the parent pipeline.
  string pipeline_id = 1;

  // Required input. Pipeline version ID to be created.
  PipelineVersion pipeline_version = 2;
}

message GetPipelineVersionRequest {
  // Required input. ID of the parent pipeline.
  string pipeline_id = 1;

  // Required input. ID of the pipeline version to be retrieved.
  string pipeline_version_id = 2;
}

message ListPipelineVersionsRequest {
  // Required input. ID of the parent pipeline.
  string pipeline_id = 1;

  // A page token to request the results page.
  string page_token = 2;

  // The number of pipeline versions to be listed per page. If there are more pipeline
  // versions than this number, the response message will contain a valid value in the
  // nextPageToken field.
  int32 page_size = 3;

  // Sorting order in form of "field_name", "field_name asc" or "field_name desc".
  // Ascending by default.
  string sort_by = 4;

  // A url-encoded, JSON-serialized filter protocol buffer (see
  // [filter.proto](https://github.com/kubeflow/pipelines/blob/master/backend/api/filter.proto)).
  string filter = 5;
}

message ListPipelineVersionsResponse {
  // Returned pipeline versions.
  repeated PipelineVersion pipeline_versions = 1;

  // The token to list the next page of pipeline versions.
  string next_page_token = 2;

  // The total number of pipeline versions for the given query.
  int32 total_size = 3;
}

message DeletePipelineVersionRequest {
  // Required input. ID of the parent pipeline.
  string pipeline_id = 1;

  // Required input. The ID of the pipeline version to be deleted.
  string pipeline_version_id = 2;
}