This is an automated email from the ASF dual-hosted git repository.
byronhsu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/submarine.git
The following commit(s) were added to refs/heads/master by this push:
new 9842769 SUBMARINE-923. [User] API documentation
9842769 is described below
commit 9842769a0a64de895226c65a014d705846cd9980
Author: jeff-901 <[email protected]>
AuthorDate: Tue Jul 13 23:10:43 2021 +0800
SUBMARINE-923. [User] API documentation
### What is this PR for?
Update the submarine rest api documentation.
### What type of PR is it?
Documentation
### Todos
### What is the Jira issue?
https://issues.apache.org/jira/browse/SUBMARINE-923
### How should this be tested?
### Screenshots (if appropriate)
### Questions:
* Do the license files need updating? No
* Are there breaking changes for older versions? No
* Does this need new documentation? No
Author: jeff-901 <[email protected]>
Signed-off-by: byronhsu <[email protected]>
Closes #671 from jeff-901/SUBMARINE-923 and squashes the following commits:
40a12ddd [jeff-901] update code spec
a6ec8f88 [jeff-901] delete redundant title
e3de4963 [jeff-901] update doc api
---
website/docs/userDocs/api/environment.md | 341 ++++++++++
website/docs/userDocs/api/experiment-template.md | 791 +++++++++++++++++++++++
website/docs/userDocs/api/experiment.md | 715 ++++++++++++++++++++
website/docs/userDocs/api/notebook.md | 303 +++++++++
4 files changed, 2150 insertions(+)
diff --git a/website/docs/userDocs/api/environment.md
b/website/docs/userDocs/api/environment.md
index 3b4c666..8559aed 100644
--- a/website/docs/userDocs/api/environment.md
+++ b/website/docs/userDocs/api/environment.md
@@ -20,3 +20,344 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+## Create Environment
+
+```
+POST /api/v1/environment
+```
+
+### Parameters
+
+Put EnvironmentSpec in request body.
+
+#### **EnvironmentSpec**
+
+| Field Name | Type | Description |
+| ----------- | ---------- | --------------------------- |
+| name | String | Environment name. |
+| dockerImage | String | Docker image name. |
+| kernelSpec | KernelSpec | Environment spec. |
+| description | String | Description of environment. |
+
+#### **KernelSpec**
+
+| Field Name | Type | Description |
+| ----------------- | -------------- | ---------------------------------- |
+| name | String | Kernel name. |
+| channels | List\<String\> | Names of the channels. |
+| condaDependencies | List\<String\> | List of kernel conda dependencies. |
+| pipDependencies | List\<String\> | List of kernel pip dependencies. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X POST -H "Content-Type: application/json" -d '
+{
+ "name": "my-submarine-env",
+ "dockerImage" : "continuumio/anaconda3",
+ "kernelSpec" : {
+ "name" : "team_default_python_3.7",
+ "channels" : ["defaults"],
+ "condaDependencies" :
+ ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+ "alabaster=0.7.12=py37_0",
+ "anaconda=2020.02=py37_0",
+ "anaconda-client=1.7.2=py37_0",
+ "anaconda-navigator=1.9.12=py37_0"],
+ "pipDependencies" :
+ ["apache-submarine==0.5.0",
+ "pyarrow==0.17.0"]
+ }
+}
+' http://127.0.0.1:32080/api/v1/environment
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "environmentId":"environment_1626160071451_0001",
+ "environmentSpec":{
+ "name":"my-submarine-env",
+ "dockerImage":"continuumio/anaconda3",
+ "kernelSpec":{
+ "name":"team_default_python_3.7",
+ "channels":["defaults"],
+ "condaDependencies":
+ ["_ipyw_jlab_nb_ext_conf\u003d0.1.0\u003dpy37_0",
+ "alabaster\u003d0.7.12\u003dpy37_0",
+ "anaconda\u003d2020.02\u003dpy37_0",
+ "anaconda-client\u003d1.7.2\u003dpy37_0",
+ "anaconda-navigator\u003d1.9.12\u003dpy37_0"],
+ "pipDependencies":
+ ["apache-submarine\u003d\u003d0.5.0",
+ "pyarrow\u003d\u003d0.17.0"]
+ },
+ "description":null,
+ "image":null
+ }
+ },
+ "attributes":{}
+}
+```
+
+## List Environment
+
+```
+GET /api/v1/environment
+```
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET http://127.0.0.1:32080/api/v1/environment
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":[
+ {
+ "environmentId":"environment_1600862964725_0002",
+ "environmentSpec":{
+ "name":"notebook-gpu-env",
+ "dockerImage":"apache/submarine:jupyter-notebook-gpu-0.6.0-SNAPSHOT",
+ "kernelSpec":{
+ "name":"submarine_jupyter_py3",
+ "channels":["defaults"],
+ "condaDependencies":[],
+ "pipDependencies":[]
+ },
+ "description":null,
+ "image":null
+ }
+ },
+ {
+ "environmentId":"environment_1626160071451_0001",
+ "environmentSpec":{
+ "name":"my-submarine-env",
+ "dockerImage":"continuumio/anaconda3",
+ "kernelSpec":{
+ "name":"team_default_python_3.7",
+ "channels":["defaults"],
+ "condaDependencies":
+ ["_ipyw_jlab_nb_ext_conf\u003d0.1.0\u003dpy37_0",
+ "alabaster\u003d0.7.12\u003dpy37_0",
+ "anaconda\u003d2020.02\u003dpy37_0",
+ "anaconda-client\u003d1.7.2\u003dpy37_0",
+ "anaconda-navigator\u003d1.9.12\u003dpy37_0"],
+ "pipDependencies":
+ ["apache-submarine\u003d\u003d0.5.0",
+ "pyarrow\u003d\u003d0.17.0"]
+ },
+ "description":null,
+ "image":null
+ }
+ },
+ {
+ "environmentId":"environment_1600862964725_0001",
+ "environmentSpec":{
+ "name":"notebook-env",
+ "dockerImage":"apache/submarine:jupyter-notebook-0.6.0-SNAPSHOT",
+ "kernelSpec":{
+ "name":"submarine_jupyter_py3",
+ "channels":["defaults"],
+ "condaDependencies":[],
+ "pipDependencies":[]
+ },
+ "description":null,
+ "image":null
+ }
+ }
+ ],
+ "attributes":{}
+}
+```
+
+## Get Environment
+
+```
+GET /api/v1/environment/{name}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description |
+| ---------- | ------ | ---- | ----------------- |
+| name | String | path | Environment name. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET http://127.0.0.1:32080/api/v1/environment/my-submarine-env
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "environmentId":"environment_1626160071451_0001",
+ "environmentSpec":{
+ "name":"my-submarine-env",
+ "dockerImage":"continuumio/anaconda3",
+ "kernelSpec":{
+ "name":"team_default_python_3.7",
+ "channels":["defaults"],
+ "condaDependencies":
+ ["_ipyw_jlab_nb_ext_conf\u003d0.1.0\u003dpy37_0",
+ "alabaster\u003d0.7.12\u003dpy37_0",
+ "anaconda\u003d2020.02\u003dpy37_0",
+ "anaconda-client\u003d1.7.2\u003dpy37_0",
+ "anaconda-navigator\u003d1.9.12\u003dpy37_0"],
+ "pipDependencies":
+ ["apache-submarine\u003d\u003d0.5.0",
+ "pyarrow\u003d\u003d0.17.0"]
+ },
+ "description":null,
+ "image":null
+ }
+ },
+ "attributes":{}
+}
+```
+
+## Patch Environment
+
+```
+PATCH /api/v1/environment/{name}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description
|
+| ----------- | ---------- | ------------- |
--------------------------------------------------- |
+| name | String | path and body | Environment name.
|
+| dockerImage | String | body | Docker image name.
|
+| kernelSpec | KernelSpec | body | Environment spec.
|
+| description | String | body | Description of environment. This
field is optional. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X PATCH -H "Content-Type: application/json" -d '
+{
+ "name": "my-submarine-env",
+ "dockerImage" : "continuumio/anaconda3",
+ "kernelSpec" : {
+ "name" : "team_default_python_3.7_updated",
+ "channels" : ["defaults"],
+ "condaDependencies" :
+ ["_ipyw_jlab_nb_ext_conf=0.1.0=py37_0",
+ "alabaster=0.7.12=py37_0"],
+ "pipDependencies" :
+ []
+ }
+}
+' http://127.0.0.1:32080/api/v1/environment/my-submarine-env
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "environmentId":"environment_1626160071451_0003",
+ "environmentSpec":{
+ "name":"my-submarine-env",
+ "dockerImage":"continuumio/anaconda3",
+ "kernelSpec":{
+ "name":"team_default_python_3.7_updated",
+ "channels":["defaults"],
+ "condaDependencies":
+ ["_ipyw_jlab_nb_ext_conf\u003d0.1.0\u003dpy37_0",
+ "alabaster\u003d0.7.12\u003dpy37_0"],
+ "pipDependencies":[]
+ },
+ "description":null,
+ "image":null
+ }
+ },
+ "attributes":{}
+}
+```
+
+### Delete Environment
+
+```
+DELETE /api/v1/environment/{name}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description |
+| ---------- | ------ | ---- | ----------------- |
+| name | String | path | Environment name. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X DELETE http://127.0.0.1:32080/api/v1/environment/my-submarine-env
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "environmentId":"environment_1626160071451_0001",
+ "environmentSpec":{
+ "name":"my-submarine-env",
+ "dockerImage":"continuumio/anaconda3",
+ "kernelSpec":{
+ "name":"team_default_python_3.7",
+ "channels":["defaults"],
+ "condaDependencies":
+ ["_ipyw_jlab_nb_ext_conf\u003d0.1.0\u003dpy37_0",
+ "alabaster\u003d0.7.12\u003dpy37_0",
+ "anaconda\u003d2020.02\u003dpy37_0",
+ "anaconda-client\u003d1.7.2\u003dpy37_0",
+ "anaconda-navigator\u003d1.9.12\u003dpy37_0"],
+ "pipDependencies":
+ ["apache-submarine\u003d\u003d0.5.0",
+ "pyarrow\u003d\u003d0.17.0"]
+ },
+ "description":null,
+ "image":null
+ }
+ },"attributes":{}
+}
+```
diff --git a/website/docs/userDocs/api/experiment-template.md
b/website/docs/userDocs/api/experiment-template.md
index 883e109..274748d 100644
--- a/website/docs/userDocs/api/experiment-template.md
+++ b/website/docs/userDocs/api/experiment-template.md
@@ -20,3 +20,794 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+## Create Experiment Template
+
+```
+POST /api/v1/template
+```
+
+### Parameters
+
+| Field Name | Type | In | Description
|
+| -------------- | ----------------------------------- | ---- |
------------------------------------------- |
+| name | String | body | Experiment
template name. This is required. |
+| author | String | body | Author name.
|
+| description | String | body | Description of
the experiment template. |
+| parameters | List\<ExperimentTemplateParamSpec\> | body | Parameters of
the experiment template. |
+| experimentSpec | ExperimentSpec | body | Spec of the
experiment template. |
+
+#### **ExperimentTemplateParamSpec**
+
+| Field Name | Type | Description |
+| ----------- | ------- | ------------------------------------------------ |
+| name | String | Parameter name. |
+| required | Boolean | true / false. Whether the parameter is required. |
+| description | String | Description of the parameter. |
+| value | String | Value of the parameter. |
+
+#### **ExperimentSpec**
+
+| Field Name | Type | Description
|
+| ----------- | --------------------------------- |
--------------------------------------- |
+| meta | ExperimentMeta | Meta data of the
experiment template. |
+| environment | EnvironmentSpec | Environment of the
experiment template. |
+| spec | Map\<String, ExperimentTaskSpec\> | Spec of pods.
|
+| code | CodeSpec | Experiment codespec.
|
+
+#### **ExperimentMeta**
+| Field Name | Type | Description |
+| ---------- | --------------------- | ------------------------ |
+| name | String | Experiment Name. |
+| namespace | String | Experiment namespace. |
+| framework | String | Experiment framework. |
+| cmd | String | Command. |
+| envVars | Map\<String, String\> | Environmental variables. |
+
+#### **EnvironmentSpec**
+
+See more details in [environment
api](https://submarine.apache.org/docs/userDocs/api/environment).
+
+#### **ExperimentTaskSpec**
+
+| Field Name | Type | Description |
+| ---------- | --------------------- | ------------------------ |
+| replicas | Integer | Numbers of replicas. |
+| resoureces | String | Resouces of the task |
+| name | String | Task name. |
+| image | String | Image name. |
+| cmd | String | Command. |
+| envVars | Map\<String, String\> | Environmental variables. |
+
+#### **CodeSpec**
+
+| Field Name | Type | Description |
+| ---------- | ------ | ----------------------- |
+| syncMode | String | sync mode of code spec. |
+| url | String | url of code spec. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X POST -H "Content-Type: application/json" -d '
+{
+ "name": "my-tf-mnist-template",
+ "author": "author",
+ "description": "This is a template to run tf-mnist",
+ "parameters": [{
+ "name": "learning_rate",
+ "value": 0.1,
+ "required": true,
+ "description": "This is learning_rate of training."
+ },
+ {
+ "name": "batch_size",
+ "value": 150,
+ "required": true,
+ "description": "This is batch_size of training."
+ },
+ {
+ "name": "experiment_name",
+ "value": "tf-mnist1",
+ "required": true,
+ "description": "the name of experiment."
+ }
+ ],
+ "experimentSpec": {
+ "meta": {
+ "cmd": "python /var/tf_mnist/mnist_with_summaries.py
--log_dir=/train/log --learning_rate={{learning_rate}}
--batch_size={{batch_size}}",
+ "name": "{{experiment_name}}",
+ "envVars": {
+ "ENV1": "ENV1"
+ },
+ "framework": "TensorFlow",
+ "namespace": "default"
+ },
+ "spec": {
+ "Ps": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=1024M"
+ },
+ "Worker": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=1024M"
+ }
+ },
+ "environment": {
+ "image": "apache/submarine:tf-mnist-with-summaries-1.0"
+ }
+ }
+}
+' http://127.0.0.1:32080/api/v1/template
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentTemplateId":{
+ "id":1,
+ "serverTimestamp":1626160071451
+ },
+ "experimentTemplateSpec":{
+ "name":"my-tf-mnist-template",
+ "author":"author",
+ "description":"This is a template to run tf-mnist",
+ "parameters":
+ [{
+ "name":"learning_rate",
+ "required":"true",
+ "description":"This is learning_rate of training.",
+ "value":"0.1"
+ },
+ {
+ "name":"batch_size",
+ "required":"true",
+ "description":"This is batch_size of training.",
+ "value":"150"
+ },
+ {
+ "name":"experiment_name",
+ "required":"true",
+ "description":"the name of experiment.",
+ "value":"tf-mnist1"
+ },
+ {
+ "name":"spec.Ps.replicas",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Ps.resourceMap.cpu",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Ps.resourceMap.memory",
+ "required":"false",
+ "description":"",
+ "value":"1024M"
+ },
+ {
+ "name":"spec.Worker.replicas",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Worker.resourceMap.cpu",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Worker.resourceMap.memory",
+ "required":"false",
+ "description":"","
+ value":"1024M"
+ }],
+ "experimentSpec":{
+ "meta":{
+ "name":"{{experiment_name}}",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d{{learning_rate}}
--batch_size\u003d{{batch_size}}",
+ "envVars":{"ENV1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{
+ "memory":"1024M",
+ "cpu":"1"
+ }
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{
+ "memory":"1024M",
+ "cpu":"1"
+ }
+ }
+ },
+ "code":null
+ }
+ }
+ },
+ "attributes":{}
+}
+```
+
+## List Experiment Template
+
+```
+GET /api/v1/template
+```
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET http://127.0.0.1:32080/api/v1/template
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ [{
+ "experimentTemplateId":{
+ "id":1,
+ "serverTimestamp":1626160071451
+ },
+ "experimentTemplateSpec":{
+ "name":"my-tf-mnist-template",
+ "author":"author",
+ "description":"This is a template to run tf-mnist",
+ "parameters":
+ [{
+ "name":"learning_rate",
+ "required":"true",
+ "description":"This is learning_rate of training.",
+ "value":"0.1"
+ },
+ {
+ "name":"batch_size",
+ "required":"true",
+ "description":"This is batch_size of training.",
+ "value":"150"
+ },
+ {
+ "name":"experiment_name",
+ "required":"true",
+ "description":"the name of experiment.",
+ "value":"tf-mnist1"
+ },
+ {
+ "name":"spec.Ps.replicas",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Ps.resourceMap.cpu",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Ps.resourceMap.memory",
+ "required":"false",
+ "description":"",
+ "value":"1024M"
+ },
+ {
+ "name":"spec.Worker.replicas",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Worker.resourceMap.cpu",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Worker.resourceMap.memory",
+ "required":"false",
+ "description":"","
+ value":"1024M"
+ }],
+ "experimentSpec":{
+ "meta":{
+ "name":"{{experiment_name}}",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d{{learning_rate}}
--batch_size\u003d{{batch_size}}",
+ "envVars":{"ENV1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{
+ "memory":"1024M",
+ "cpu":"1"
+ }
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{
+ "memory":"1024M",
+ "cpu":"1"
+ }
+ }
+ },
+ "code":null
+ }
+ }
+ }],
+ "attributes":{}
+}
+```
+
+## Patch Experiment Template
+
+```
+PATCH /api/v1/template{name}
+```
+
+### Parameters
+
+| Field Name | Type | In |
Description |
+| -------------- | ----------------------------------- | ------------- |
------------------------------------------- |
+| name | String | path and body |
Experiment template name. This is required. |
+| author | String | body |
Author name. |
+| description | String | body |
Description of the experiment template. |
+| parameters | List\<ExperimentTemplateParamSpec\> | body |
Parameters of the experiment template. |
+| experimentSpec | ExperimentSpec | body | Spec
of the experiment template. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X PATCH -H "Content-Type: application/json" -d '
+{
+ "name": "my-tf-mnist-template",
+ "author": "author-new",
+ "description": "This is a template to run tf-mnist",
+ "parameters": [{
+ "name": "learning_rate",
+ "value": 0.1,
+ "required": true,
+ "description": "This is learning_rate of training."
+ },
+ {
+ "name": "batch_size",
+ "value": 150,
+ "required": true,
+ "description": "This is batch_size of training."
+ },
+ {
+ "name": "experiment_name",
+ "value": "tf-mnist1",
+ "required": true,
+ "description": "the name of experiment."
+ }
+ ],
+ "experimentSpec": {
+ "meta": {
+ "cmd": "python /var/tf_mnist/mnist_with_summaries.py
--log_dir=/train/log --learning_rate={{learning_rate}}
--batch_size={{batch_size}}",
+ "name": "{{experiment_name}}",
+ "envVars": {
+ "ENV1": "ENV1"
+ },
+ "framework": "TensorFlow",
+ "namespace": "default"
+ },
+ "spec": {
+ "Ps": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=1024M"
+ },
+ "Worker": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=1024M"
+ }
+ },
+ "environment": {
+ "image": "apache/submarine:tf-mnist-with-summaries-1.0"
+ }
+ }
+}
+' http://127.0.0.1:32080/api/v1/template/my-tf-mnist-template
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentTemplateId":{
+ "id":2,
+ "serverTimestamp":1626160071451
+ },
+ "experimentTemplateSpec":{
+ "name":"my-tf-mnist-template",
+ "author":"author-new",
+ "description":"This is a template to run tf-mnist",
+ "parameters":
+ [{
+ "name":"learning_rate",
+ "required":"true",
+ "description":"This is learning_rate of training.",
+ "value":"0.1"
+ },
+ {
+ "name":"batch_size",
+ "required":"true",
+ "description":"This is batch_size of training.",
+ "value":"150"
+ },
+ {
+ "name":"experiment_name",
+ "required":"true",
+ "description":"the name of experiment.",
+ "value":"tf-mnist1"
+ },
+ {
+ "name":"spec.Ps.replicas",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Ps.resourceMap.cpu",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Ps.resourceMap.memory",
+ "required":"false",
+ "description":"",
+ "value":"1024M"
+ },
+ {
+ "name":"spec.Worker.replicas",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Worker.resourceMap.cpu",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Worker.resourceMap.memory",
+ "required":"false",
+ "description":"",
+ "value":"1024M"
+ }],
+ "experimentSpec":{
+ "meta":{
+ "name":"{{experiment_name}}",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d{{learning_rate}}
--batch_size\u003d{{batch_size}}",
+ "envVars":{"ENV1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ }
+ },
+ "attributes":{}
+}
+```
+
+## Delete Experiment Template
+
+```
+DELETE /api/v1/template{name}
+```
+
+### Parameters
+| Field Name | Type | In | Description |
+| ---------- | ------ | ---- | ------------------------------------------- |
+| name | String | path | Experiment template name. This is required. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X DELETE http://127.0.0.1:32080/api/v1/template/my-tf-mnist-template
+```
+
+**reponse**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentTemplateId":{
+ "id":2,
+ "serverTimestamp":1626160071451
+ },
+ "experimentTemplateSpec":{
+ "name":"my-tf-mnist-template",
+ "author":"author-new",
+ "description":"This is a template to run tf-mnist",
+ "parameters":
+ [{
+ "name":"learning_rate",
+ "required":"true",
+ "description":"This is learning_rate of training.",
+ "value":"0.1"
+ },
+ {
+ "name":"batch_size",
+ "required":"true",
+ "description":"This is batch_size of training.",
+ "value":"150"
+ },
+ {
+ "name":"experiment_name",
+ "required":"true",
+ "description":"the name of experiment.",
+ "value":"tf-mnist1"
+ },
+ {
+ "name":"spec.Ps.replicas",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Ps.resourceMap.cpu",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Ps.resourceMap.memory",
+ "required":"false",
+ "description":"",
+ "value":"1024M"
+ },
+ {
+ "name":"spec.Worker.replicas",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Worker.resourceMap.cpu",
+ "required":"false",
+ "description":"",
+ "value":"1"
+ },
+ {
+ "name":"spec.Worker.resourceMap.memory",
+ "required":"false",
+ "description":"",
+ "value":"1024M"
+ }],
+ "experimentSpec":{
+ "meta":{
+ "name":"{{experiment_name}}",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d{{learning_rate}}
--batch_size\u003d{{batch_size}}",
+ "envVars":{"ENV1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ }
+ },
+ "attributes":{}
+}
+```
+
+## Use Template to Create a Experiment
+
+```
+POST /api/v1/experiment/{template_name}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description
|
+| ------------- | ------------------- | ---- |
--------------------------------------------------------- |
+| template_name | String | path | Experiment template name.
|
+| name | String | body | Experiment template name.
|
+| params | Map<String, String> | body | Parameters of the experiment
including `experiment_name`. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X POST -H "Content-Type: application/json" -d '
+{
+ "name": "tf-mnist",
+ "params": {
+ "learning_rate":"0.01",
+ "batch_size":"150",
+ "experiment_name":"newexperiment1"
+ }
+}
+' http://127.0.0.1:32080/api/v1/experiment/my-tf-mnist-template
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentId":"experiment_1626160071451_0001",
+ "name":"newexperiment1",
+ "uid":"b895985c-411c-4e89-90e0-c60a2a8a4235",
+ "status":"Accepted",
+ "acceptedTime":"2021-07-13T16:21:31.000+08:00",
+ "createdTime":null,
+ "runningTime":null,
+ "finishedTime":null,
+ "spec":{
+ "meta":{
+ "name":"newexperiment1",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d0.01 --batch_size\u003d150",
+ "envVars":{"ENV1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ },
+ "attributes":{}
+}
+```
diff --git a/website/docs/userDocs/api/experiment.md
b/website/docs/userDocs/api/experiment.md
index 3befe01..e2e534a 100644
--- a/website/docs/userDocs/api/experiment.md
+++ b/website/docs/userDocs/api/experiment.md
@@ -20,3 +20,718 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+## Create Experiment (Using Anonymous/Embedded Environment)
+
+```sh
+POST /api/v1/experiment
+```
+
+### Parameters
+
+Put ExperimentSpec in request body.
+
+#### **ExperimentSpec**
+
+| Field Name | Type | Description
|
+| ----------- | --------------------------------- |
--------------------------------------- |
+| meta | ExperimentMeta | Meta data of the
experiment template. |
+| environment | EnvironmentSpec | Environment of the
experiment template. |
+| spec | Map\<String, ExperimentTaskSpec\> | Spec of pods.
|
+| code | CodeSpec | Experiment codespec.
|
+
+#### **ExperimentMeta**
+
+| Field Name | Type | Description |
+| ---------- | --------------------- | ------------------------ |
+| name | String | Experiment name. |
+| namespace | String | Experiment namespace. |
+| framework | String | Experiemnt framework. |
+| cmd | String | Command. |
+| envVars | Map\<String, String\> | Environmental variables. |
+
+#### **EnvironmentSpec**
+
+See more details in [environment
api](https://submarine.apache.org/docs/userDocs/api/environment).
+
+#### **ExperimentTaskSpec**
+
+| Field Name | Type | Description |
+| ---------- | --------------------- | ------------------------ |
+| replicas | Integer | Numbers of replicas. |
+| resoureces | String | Resouces of the task |
+| name | String | Task name. |
+| image | String | Image name. |
+| cmd | String | Command. |
+| envVars | Map\<String, String\> | Environmental variables. |
+
+#### **CodeSpec**
+
+| Field Name | Type | Description |
+| ---------- | ------ | ----------------------- |
+| syncMode | String | sync mode of code spec. |
+| url | String | url of code spec. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X POST -H "Content-Type: application/json" -d '
+{
+ "meta": {
+ "name": "tf-mnist-json",
+ "namespace": "default",
+ "framework": "TensorFlow",
+ "cmd": "python /var/tf_mnist/mnist_with_summaries.py --log_dir=/train/log
--learning_rate=0.01 --batch_size=150",
+ "envVars": {
+ "ENV_1": "ENV1"
+ }
+ },
+ "environment": {
+ "image": "apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec": {
+ "Ps": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=1024M"
+ },
+ "Worker": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=2048M"
+ }
+ }
+}
+' http://127.0.0.1:32080/api/v1/experiment
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentId":"experiment_1626160071451_0002",
+ "name":"tf-mnist-json",
+ "uid":"5a6ec922-6c90-43d4-844f-039f6804ed36",
+ "status":"Accepted",
+ "acceptedTime":"2021-07-13T16:47:51.000+08:00",
+ "createdTime":null,
+ "runningTime":null,
+ "finishedTime":null,
+ "spec":{
+ "meta":{
+ "name":"tf-mnist-json",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d0.01 --batch_size\u003d150",
+ "envVars":{"ENV_1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d2048M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"2048M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ },
+ "attributes":{}
+}
+```
+
+## Create Experiment (Using Pre-defined/Stored Environment)
+
+```
+POST /api/v1/experiment
+```
+
+### Parameters
+
+Put ExperimentSpec in request body.
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X POST -H "Content-Type: application/json" -d '
+{
+ "meta": {
+ "name": "tf-mnist-json",
+ "namespace": "default",
+ "framework": "TensorFlow",
+ "cmd": "python /var/tf_mnist/mnist_with_summaries.py --log_dir=/train/log
--learning_rate=0.01 --batch_size=150",
+ "envVars": {
+ "ENV_1": "ENV1"
+ }
+ },
+ "environment": {
+ "name": "my-submarine-env"
+ },
+ "spec": {
+ "Ps": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=1024M"
+ },
+ "Worker": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=2048M"
+ }
+ }
+}
+' http://127.0.0.1:32080/api/v1/experiment
+```
+Above example assume environment "my-submarine-env" already exists in
Submarine. Please refer Environment API Reference doc to [environment rest
api](https://submarine.apache.org/docs/userDocs/api/environment).
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentId":"experiment_1626160071451_0005",
+ "name":"tf-mnist-json",
+ "uid":"4944c603-0f21-49e5-826a-2ff820bb4d93",
+ "status":"Accepted",
+ "acceptedTime":"2021-07-13T16:57:27.000+08:00",
+ "createdTime":null,
+ "runningTime":null,
+ "finishedTime":null,
+ "spec":{
+ "meta":{
+ "name":"tf-mnist-json",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d0.01 --batch_size\u003d150",
+ "envVars":{"ENV_1":"ENV1"}
+ },
+ "environment":{
+ "name":"my-submarine-env",
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":null
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d2048M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"2048M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ },
+ "attributes":{}
+}
+```
+
+## List Experiment
+
+```
+GET /api/v1/experiment
+```
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET http://127.0.0.1:32080/api/v1/experiment
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":
+ [{
+ "experimentId":"experiment_1626160071451_0001",
+ "name":"newexperiment1",
+ "uid":"b895985c-411c-4e89-90e0-c60a2a8a4235",
+ "status":"Succeeded",
+ "acceptedTime":"2021-07-13T16:21:31.000+08:00",
+ "createdTime":"2021-07-13T16:21:31.000+08:00",
+ "runningTime":"2021-07-13T16:21:46.000+08:00",
+ "finishedTime":"2021-07-13T16:26:54.000+08:00",
+ "spec":{
+ "meta":{
+ "name":"newexperiment1",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d0.01 --batch_size\u003d150",
+ "envVars":{"ENV1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ },
+ {
+ "experimentId":"experiment_1626160071451_0005",
+ "name":"tf-mnist-json",
+ "uid":"4944c603-0f21-49e5-826a-2ff820bb4d93",
+ "status":"Accepted",
+ "acceptedTime":"2021-07-13T16:57:27.000+08:00",
+ "createdTime":null,
+ "runningTime":null,
+ "finishedTime":null,
+ "spec":{
+ "meta":{
+ "name":"tf-mnist-json",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d0.01 --batch_size\u003d150",
+ "envVars":{"ENV_1":"ENV1"}
+ },
+ "environment":{
+ "name":"my-submarine-env",
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":null
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d2048M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"2048M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ }],
+ "attributes":{}
+}
+```
+
+## Get Experiment
+
+```
+GET /api/v1/experiment/{id}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description |
+| ---------- | ------ | ---- | -------------- |
+| id | String | path | Experiment id. |
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET
http://127.0.0.1:32080/api/v1/experiment/experiment_1626160071451_0005
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentId":"experiment_1626160071451_0005",
+ "name":"tf-mnist-json",
+ "uid":"4944c603-0f21-49e5-826a-2ff820bb4d93",
+ "status":"Accepted",
+ "acceptedTime":"2021-07-13T16:57:27.000+08:00",
+ "createdTime":null,
+ "runningTime":null,
+ "finishedTime":null,
+ "spec":{
+ "meta":{
+ "name":"tf-mnist-json",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d0.01 --batch_size\u003d150",
+ "envVars":{"ENV_1":"ENV1"}
+ },
+ "environment":{
+ "name":"my-submarine-env",
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":null
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d2048M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"2048M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ },
+ "attributes":{}
+}
+```
+
+## Patch Experiment
+
+```
+PATCH /api/v1/experiment/{id}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description
|
+| ----------- | --------------------------------- | ---- |
--------------------------------------- |
+| id | String | path | Experiment id.
|
+| meta | ExperimentMeta | body | Meta data of the
experiment template. |
+| environment | EnvironmentSpec | body | Environment of the
experiment template. |
+| spec | Map\<String, ExperimentTaskSpec\> | body | Spec of pods.
|
+| code | CodeSpec | body | TODO
|
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X PATCH -H "Content-Type: application/json" -d '
+{
+ "meta": {
+ "name": "tf-mnist-json",
+ "namespace": "default",
+ "framework": "TensorFlow",
+ "cmd": "python /var/tf_mnist/mnist_with_summaries.py --log_dir=/train/log
--learning_rate=0.01 --batch_size=150",
+ "envVars": {
+ "ENV_1": "ENV1"
+ }
+ },
+ "environment": {
+ "image": "apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec": {
+ "Ps": {
+ "replicas": 1,
+ "resources": "cpu=1,memory=1024M"
+ },
+ "Worker": {
+ "replicas": 2,
+ "resources": "cpu=1,memory=2048M"
+ }
+ }
+}
+' http://127.0.0.1:32080/api/v1/experiment/experiment_1626160071451_0005
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentId":"experiment_1626160071451_0005",
+ "name":"tf-mnist-json",
+ "uid":"4944c603-0f21-49e5-826a-2ff820bb4d93",
+ "status":"Accepted",
+ "acceptedTime":"2021-07-13T16:57:27.000+08:00",
+ "createdTime":null,
+ "runningTime":null,
+ "finishedTime":null,
+ "spec":{
+ "meta":{
+ "name":"tf-mnist-json",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d0.01 --batch_size\u003d150",
+ "envVars":{"ENV_1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":2,
+ "resources":"cpu\u003d1,memory\u003d2048M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"2048M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ },
+ "attributes":{}
+}
+```
+
+### Delete Experiment
+
+```
+DELETE /api/v1/experiment/{id}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description |
+| ---------- | ------ | ---- | -------------- |
+| id | String | path | Experiment id. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X DELETE
http://127.0.0.1:32080/api/v1/experiment/experiment_1626160071451_0005
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentId":"experiment_1626160071451_0005",
+ "name":"tf-mnist-json",
+ "uid":"4944c603-0f21-49e5-826a-2ff820bb4d93",
+ "status":"Deleted",
+ "acceptedTime":null,
+ "createdTime":null,
+ "runningTime":null,
+ "finishedTime":null,
+ "spec":{
+ "meta":{
+ "name":"tf-mnist-json",
+ "namespace":"default",
+ "framework":"TensorFlow",
+ "cmd":"python /var/tf_mnist/mnist_with_summaries.py
--log_dir\u003d/train/log --learning_rate\u003d0.01 --batch_size\u003d150",
+ "envVars":{"ENV_1":"ENV1"}
+ },
+ "environment":{
+ "name":null,
+ "dockerImage":null,
+ "kernelSpec":null,
+ "description":null,
+ "image":"apache/submarine:tf-mnist-with-summaries-1.0"
+ },
+ "spec":{
+ "Ps":{
+ "replicas":1,
+ "resources":"cpu\u003d1,memory\u003d1024M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"1024M","cpu":"1"}
+ },
+ "Worker":{
+ "replicas":2,
+ "resources":"cpu\u003d1,memory\u003d2048M",
+ "name":null,
+ "image":null,
+ "cmd":null,
+ "envVars":null,
+ "resourceMap":{"memory":"2048M","cpu":"1"}
+ }
+ },
+ "code":null
+ }
+ },
+ "attributes":{}
+}
+```
+
+## List Experiment Log
+
+```
+GET /api/v1/experiment/logs
+```
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET http://127.0.0.1:32080/api/v1/experiment/logs
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":
+ [{
+ "experimentId":"experiment_1626160071451_0001",
+ "logContent":
+ [{
+ "podName":"newexperiment1-ps-0",
+ "podLog":[]
+ },
+ {
+ "podName":"newexperiment1-worker-0",
+ "podLog":[]
+ }]
+ }],
+ "attributes":{}
+}
+```
+
+## Get Experiment Log
+
+```
+GET /api/v1/experiment/logs/{id}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description |
+| ---------- | ------ | ---- | -------------- |
+| id | String | path | Experiment id. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET
http://127.0.0.1:32080/api/v1/experiment/logs/experiment_1626160071451_0001
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":null,
+ "result":{
+ "experimentId":"experiment_1626160071451_0001",
+ "logContent":
+ [{
+ "podName":"newexperiment1-ps-0",
+ "podLog":[]
+ },
+ {
+ "podName":"newexperiment1-worker-0",
+ "podLog":[]
+ }]
+ },
+ "attributes":{}
+}
+```
diff --git a/website/docs/userDocs/api/notebook.md
b/website/docs/userDocs/api/notebook.md
index 96f6c87..f3e2ee6 100644
--- a/website/docs/userDocs/api/notebook.md
+++ b/website/docs/userDocs/api/notebook.md
@@ -20,3 +20,306 @@ KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
+
+## Create a Notebook Instance
+
+```
+POST /api/v1/notebook
+```
+
+### Parameters
+
+NotebookSpec in request body.
+
+#### **NotebookSpec**
+
+| Field Name | Type | Description |
+| ----------- | --------------- | --------------------------------------- |
+| meta | NotebookMeta | Meta data of the notebook. |
+| environment | EnvironmentSpec | Environment of the experiment template. |
+| spec | NotebookPodSpec | Spec of the notebook pods. |
+
+#### **NotebookMeta**
+
+| Field Name | Type | Description |
+| ---------- | ------ | ------------------- |
+| name | String | Notebook name. |
+| namespace | String | Notebook namespace. |
+| ownerId | String | User id. |
+
+#### **EnvironmentSpec**
+
+See more details in [environment
api](https://submarine.apache.org/docs/userDocs/api/environment).
+
+#### **NotebookPodSpec**
+
+| Field Name | Type | Description |
+| ---------- | --------------------- | ------------------------ |
+| envVars | Map\<String, String\> | Environmental variables. |
+| resources | String | Resourecs of the pod. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X POST -H "Content-Type: application/json" -d '
+{
+ "meta": {
+ "name": "test-nb",
+ "namespace": "default",
+ "ownerId": "e9ca23d68d884d4ebb19d07889727dae"
+ },
+ "environment": {
+ "name": "notebook-env"
+ },
+ "spec": {
+ "envVars": {
+ "TEST_ENV": "test"
+ },
+ "resources": "cpu=1,memory=1.0Gi"
+ }
+}
+' http://127.0.0.1:32080/api/v1/notebook
+```
+
+**response:**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":"Create a notebook instance",
+ "result":{
+ "notebookId":"notebook_1626160071451_0001",
+ "name":"test-nb",
+ "uid":"a56713da-f2a3-40d0-ae2e-45fdc0bb15f5",
+ "url":"/notebook/default/test-nb/lab",
+ "status":"creating",
+ "reason":"The notebook instance is creating",
+ "createdTime":"2021-07-13T16:23:38.000+08:00",
+ "deletedTime":null,
+ "spec":{
+ "meta":{
+ "name":"test-nb",
+ "namespace":"default",
+ "ownerId":"e9ca23d68d884d4ebb19d07889727dae"
+ },
+ "environment":{
+ "name":"notebook-env",
+ "dockerImage":"apache/submarine:jupyter-notebook-0.6.0-SNAPSHOT",
+ "kernelSpec":{
+ "name":"submarine_jupyter_py3",
+ "channels":["defaults"],
+ "condaDependencies":[],
+ "pipDependencies":[]
+ },
+ "description":null,
+ "image":null
+ },
+ "spec":{
+ "envVars":{"TEST_ENV":"test"},
+ "resources":"cpu\u003d1,memory\u003d1.0Gi"
+ }
+ }
+ },
+ "attributes":{}
+}
+```
+
+## List notebook instances which belong to user
+
+```
+GET /api/v1/notebook
+```
+
+### Parameters
+
+| Field Name | Type | In | Description |
+| ---------- | ------ | ----- | ----------- |
+| id | String | query | User id. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET
http://127.0.0.1:32080/api/v1/notebook?id=e9ca23d68d884d4ebb19d07889727dae
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":"List all notebook instances",
+ "result":
+ [{
+ "notebookId":"notebook_1626160071451_0001",
+ "name":"test-nb",
+ "uid":"a56713da-f2a3-40d0-ae2e-45fdc0bb15f5",
+ "url":"/notebook/default/test-nb/lab",
+ "status":"waiting",
+ "reason":"ContainerCreating",
+ "createdTime":"2021-07-13T16:23:38.000+08:00",
+ "deletedTime":null,
+ "spec":{
+ "meta":{
+ "name":"test-nb",
+ "namespace":"default",
+ "ownerId":"e9ca23d68d884d4ebb19d07889727dae"
+ },
+ "environment":{
+ "name":"notebook-env",
+ "dockerImage":"apache/submarine:jupyter-notebook-0.6.0-SNAPSHOT",
+ "kernelSpec":{
+ "name":"submarine_jupyter_py3",
+ "channels":["defaults"],
+ "condaDependencies":[],
+ "pipDependencies":[]
+ },
+ "description":null,
+ "image":null
+ },
+ "spec":{
+ "envVars":{"TEST_ENV":"test"},
+ "resources":"cpu\u003d1,memory\u003d1.0Gi"
+ }
+ }
+ }],
+ "attributes":{}
+}
+```
+
+## Get the notebook instance
+
+```
+GET /api/v1/notebook/{id}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description |
+| ---------- | ------ | ---- | ------------ |
+| id | String | path | Notebook id. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X GET http://127.0.0.1:32080/api/v1/notebook/notebook_1626160071451_0001
+```
+
+**response**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":"Get the notebook instance",
+ "result":{
+ "notebookId":"notebook_1626160071451_0001",
+ "name":"test-nb",
+ "uid":"a56713da-f2a3-40d0-ae2e-45fdc0bb15f5",
+ "url":"/notebook/default/test-nb/lab",
+ "status":"waiting",
+ "reason":"ContainerCreating",
+ "createdTime":"2021-07-13T16:23:38.000+08:00",
+ "deletedTime":null,
+ "spec":{
+ "meta":{
+ "name":"test-nb",
+ "namespace":"default",
+ "ownerId":"e9ca23d68d884d4ebb19d07889727dae"
+ },
+ "environment":{
+ "name":"notebook-env",
+ "dockerImage":"apache/submarine:jupyter-notebook-0.6.0-SNAPSHOT",
+ "kernelSpec":{
+ "name":"submarine_jupyter_py3",
+ "channels":["defaults"],
+ "condaDependencies":[],
+ "pipDependencies":[]
+ },
+ "description":null,
+ "image":null
+ },
+ "spec":{
+ "envVars":{"TEST_ENV":"test"},
+ "resources":"cpu\u003d1,memory\u003d1.0Gi"
+ }
+ }
+ },
+ "attributes":{}
+}
+```
+
+## Delete the notebook instance
+
+```
+DELETE /api/v1/notebook/{id}
+```
+
+### Parameters
+
+| Field Name | Type | In | Description |
+| ---------- | ------ | ---- | ------------ |
+| id | String | path | Notebook id. |
+
+### Code Example
+
+**shell**
+
+```sh
+curl -X DELETE
http://127.0.0.1:32080/api/v1/notebook/notebook_1626160071451_0001
+```
+
+**response:**
+
+```json
+{
+ "status":"OK",
+ "code":200,
+ "success":true,
+ "message":"Delete the notebook instance",
+ "result":{
+ "notebookId":"notebook_1626160071451_0001",
+ "name":"test-nb",
+ "uid":"a56713da-f2a3-40d0-ae2e-45fdc0bb15f5",
+ "url":"/notebook/default/test-nb/lab",
+ "status":"terminating",
+ "reason":"The notebook instance is terminating",
+ "createdTime":"2021-07-13T16:23:38.000+08:00",
+ "deletedTime":null,
+ "spec":{
+ "meta":{
+ "name":"test-nb",
+ "namespace":"default",
+ "ownerId":"e9ca23d68d884d4ebb19d07889727dae"
+ },
+ "environment":{
+ "name":"notebook-env",
+ "dockerImage":"apache/submarine:jupyter-notebook-0.6.0-SNAPSHOT",
+ "kernelSpec":{
+ "name":"submarine_jupyter_py3",
+ "channels":["defaults"],
+ "condaDependencies":[],
+ "pipDependencies":[]
+ },
+ "description":null,
+ "image":null
+ },
+ "spec":{
+ "envVars":{"TEST_ENV":"test"},
+ "resources":"cpu\u003d1,memory\u003d1.0Gi"
+ }
+ }
+ },
+ "attributes":{}
+}
+```
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
