pipelines/backend/api/v2beta1/experiment.proto

// 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/empty.proto";
import "google/protobuf/timestamp.proto";

service ExperimentService {
  // Creates a new experiment.
  rpc CreateExperiment(CreateExperimentRequest) returns (Experiment) {
    option (google.api.http) = {
      post: "/apis/v2beta1/experiments"
      body: "experiment"
    };
  }

  // Finds a specific experiment by ID.
  rpc GetExperiment(GetExperimentRequest) returns (Experiment) {
    option (google.api.http) = {
      get: "/apis/v2beta1/experiments/{experiment_id}"
    };
  }

  // Finds all experiments. Supports pagination, and sorting on certain fields.
  rpc ListExperiments(ListExperimentsRequest) returns (ListExperimentsResponse) {
    option (google.api.http) = {
      get: "/apis/v2beta1/experiments"
    };
  }

  // Archives an experiment and the experiment's runs and recurring runs.
  rpc ArchiveExperiment(ArchiveExperimentRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v2beta1/experiments/{experiment_id}:archive"
    };
  }

  // Restores an archived experiment. The experiment's archived runs and recurring
  // runs will stay archived.
  rpc UnarchiveExperiment(UnarchiveExperimentRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      post: "/apis/v2beta1/experiments/{experiment_id}:unarchive"
    };
  }

  // Deletes an experiment without deleting the experiment's runs and recurring 
  // runs. To avoid unexpected behaviors, delete an experiment's runs and recurring 
  // runs before deleting the experiment.
  rpc DeleteExperiment(DeleteExperimentRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/apis/v2beta1/experiments/{experiment_id}"
    };
  }
}

message Experiment {
  // Output. Unique experiment ID. Generated by API server.
  string experiment_id = 1;

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

  // Optional input field. Describes the purpose of the experiment.
  string description = 3;

  // Output. The time that the experiment was created.
  google.protobuf.Timestamp created_at = 4;

  // Optional input field. Specify the namespace this experiment belongs to.
  string namespace = 5;

  // Describes whether an entity is available or archived.
  enum StorageState {
    // Default state. This state in not used
    STORAGE_STATE_UNSPECIFIED = 0;

    // Entity is available.
    AVAILABLE = 1;

    // Entity is archived.
    ARCHIVED = 2;
  }

  // Output. Specifies whether this experiment is in archived or available state.
  StorageState storage_state = 6;
}

message CreateExperimentRequest {
  // The experiment to be created.
  Experiment experiment = 1;
}

message GetExperimentRequest {
  // The ID of the experiment to be retrieved.
  string experiment_id = 1;
}

message ListExperimentsRequest {
  // A page token to request the next page of results. The token is acquried
  // from the nextPageToken field of the response from the previous
  // ListExperiments call or can be omitted when fetching the first page.
  string page_token = 1;

  // The number of experiments to be listed per page. If there are more
  // experiments than this number, the response message will contain a
  // nextPageToken field you can use to fetch the next page.
  int32 page_size = 2;

  // Can be format of "field_name", "field_name asc" or "field_name desc"
  // Ascending by default.
  string sort_by = 3;

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

 // Which namespace to filter the experiments on.
  string namespace = 5;
}

message ListExperimentsResponse {
  // A list of experiments returned.
  repeated Experiment experiments = 1;

  // The number of experiments for the given query.
  int32 total_size = 3;

  // The token to list the next page of experiments.
  string next_page_token = 2;
}

message DeleteExperimentRequest {
  // The ID of the experiment to be deleted.
  string experiment_id = 1;
}

message ArchiveExperimentRequest {
  // The ID of the experiment to be archived.
  string experiment_id = 1;
}

message UnarchiveExperimentRequest {
  // The ID of the experiment to be restored.
  string experiment_id = 1;
}