From d31bb40701cbcb981cd230063aff759a3e55dd3e Mon Sep 17 00:00:00 2001 From: zzxwill Date: Mon, 24 Aug 2020 18:02:19 +0800 Subject: [PATCH] Add Restful API reference added Restful API reference for dashboard development and move cli docs to `documentation/cli` --- .../api/vela-restful-api-reference.md | 563 ++++++++++++++++++ documentation/{ => cli}/vela.md | 0 documentation/{ => cli}/vela_app_delete.md | 0 documentation/{ => cli}/vela_app_ls.md | 0 documentation/{ => cli}/vela_app_run.md | 0 documentation/{ => cli}/vela_app_show.md | 0 documentation/{ => cli}/vela_app_status.md | 0 documentation/{ => cli}/vela_cap_add.md | 0 .../{ => cli}/vela_cap_center_config.md | 0 .../{ => cli}/vela_cap_center_sync.md | 0 documentation/{ => cli}/vela_cap_ls.md | 0 documentation/{ => cli}/vela_cap_remove.md | 0 documentation/{ => cli}/vela_comp_run.md | 0 documentation/{ => cli}/vela_completion.md | 0 .../{ => cli}/vela_completion_bash.md | 0 .../{ => cli}/vela_completion_zsh.md | 0 documentation/{ => cli}/vela_dashboard.md | 0 documentation/cli/vela_deployment_run.md | 40 ++ documentation/{ => cli}/vela_env.md | 0 documentation/{ => cli}/vela_env_delete.md | 0 documentation/{ => cli}/vela_env_init.md | 0 documentation/{ => cli}/vela_env_sw.md | 0 documentation/{ => cli}/vela_rollout.md | 0 .../{ => cli}/vela_rollout_detach.md | 0 documentation/{ => cli}/vela_scale.md | 0 documentation/{ => cli}/vela_scale_detach.md | 0 documentation/{ => cli}/vela_system_info.md | 0 documentation/{ => cli}/vela_system_init.md | 0 documentation/{ => cli}/vela_system_update.md | 0 documentation/{ => cli}/vela_traits.md | 0 documentation/{ => cli}/vela_version.md | 0 documentation/{ => cli}/vela_workloads.md | 0 32 files changed, 603 insertions(+) create mode 100644 documentation/api/vela-restful-api-reference.md rename documentation/{ => cli}/vela.md (100%) rename documentation/{ => cli}/vela_app_delete.md (100%) rename documentation/{ => cli}/vela_app_ls.md (100%) rename documentation/{ => cli}/vela_app_run.md (100%) rename documentation/{ => cli}/vela_app_show.md (100%) rename documentation/{ => cli}/vela_app_status.md (100%) rename documentation/{ => cli}/vela_cap_add.md (100%) rename documentation/{ => cli}/vela_cap_center_config.md (100%) rename documentation/{ => cli}/vela_cap_center_sync.md (100%) rename documentation/{ => cli}/vela_cap_ls.md (100%) rename documentation/{ => cli}/vela_cap_remove.md (100%) rename documentation/{ => cli}/vela_comp_run.md (100%) rename documentation/{ => cli}/vela_completion.md (100%) rename documentation/{ => cli}/vela_completion_bash.md (100%) rename documentation/{ => cli}/vela_completion_zsh.md (100%) rename documentation/{ => cli}/vela_dashboard.md (100%) create mode 100644 documentation/cli/vela_deployment_run.md rename documentation/{ => cli}/vela_env.md (100%) rename documentation/{ => cli}/vela_env_delete.md (100%) rename documentation/{ => cli}/vela_env_init.md (100%) rename documentation/{ => cli}/vela_env_sw.md (100%) rename documentation/{ => cli}/vela_rollout.md (100%) rename documentation/{ => cli}/vela_rollout_detach.md (100%) rename documentation/{ => cli}/vela_scale.md (100%) rename documentation/{ => cli}/vela_scale_detach.md (100%) rename documentation/{ => cli}/vela_system_info.md (100%) rename documentation/{ => cli}/vela_system_init.md (100%) rename documentation/{ => cli}/vela_system_update.md (100%) rename documentation/{ => cli}/vela_traits.md (100%) rename documentation/{ => cli}/vela_version.md (100%) rename documentation/{ => cli}/vela_workloads.md (100%) diff --git a/documentation/api/vela-restful-api-reference.md b/documentation/api/vela-restful-api-reference.md new file mode 100644 index 000000000..3101fc41f --- /dev/null +++ b/documentation/api/vela-restful-api-reference.md @@ -0,0 +1,563 @@ +# vela Restful API Reference + +# API response introduction +### The API response contains two keys: `code` and `data` +The API response is in `json` format which contains two keys: `code` and `data`. +```json +{ + "code": RESPONSE_CODE, + "data": RESPONSE_DATA +} +``` + +### `code` represents the status of a request +The type of `code` is `Number`, currently it allows two codes. +- 200 - StatusOK +- 500 - StatusInternalServerError + +### `data` represents the response data. +- code == 500 + +`data` contains the error message. + +- code == 200 + +The type of `data` is `Object` or `Object` list if method is `Get`, or is `String` type the content of which represents +the successful message. + +# API list +## Env +### POST /api/envs/ (env init) +- example + +sample request: +```json +{"name":"ccc","namespace":"ccc"} +``` + +sample response: +```json +{ +"code": 200, +"data": "Create env succeed, current env is ccc namespace is ccc, use --namespace= to specify namespace with env:init" +} +``` + +### GET /api/envs/ (env list) +- Response +`current` of the elment of `data` indicates the currently using environment. + +- example + +sample response: +```json +{ + "code": 200, + "data": [{ + "name": "ccc", + "current": "*", + "namespace": "ccc" + }, { + "name": "default", + "namespace": "default" + }, { + "name": "env-application", + "namespace": "env-application" + }, { + "name": "env-hello", + "namespace": "env-hello" + }, { + "name": "env-poc", + "namespace": "env-poc" + }, { + "name": "env-trait", + "namespace": "env-trait" + }, { + "name": "env-workload", + "namespace": "env-workload" + }] +} +``` + +### Get /api/envs/:envName (env description) +- example +sample response +```json +{"code":200,"data":[{"name":"ccc","namespace":"ccc"}]} +``` + +### DELETE /api/envs/:envName (env delete) +- example +sample response +```json +{ +"code": 200, +"data": "abcd deleted" +} +``` + +```json +{ +"code": 500, +"data": "you can't delete current using env abc" +} +``` + +### PATCH /api/envs/:envName (env switch) +- example +sample response +```json +{"code":200,"data":"Switch env succeed, current env is default, namespace is default"} +``` + +```json +{"code":500,"data":"abcd not exist"} +``` + +## Application +### GET /api/envs/default/apps/ (app list) +- response +`status` of the element of `data` represents the status of the application + * True：normal + * False：fatal + * UNKNOWN：deploying + +- example +sample response +```json +{ + "code": 200, + "data": [{ + "name": "poc2040", + "workload": "ContainerizedWorkload", + "status": "True", + "created": "2020-08-17 15:09:27 +0800 CST" + }] +} +``` + +```json +{ + "code": 500, + "data": "hit some issues" +} +``` + +### GET /api/envs/:envName/apps/:appName (app description) +- example +sample response +```json +{ + "code": 200, + "data": { + "Status": "UNKNOWN", + "Workload": { + "workload": { + "apiVersion": "core.oam.dev/v1alpha2", + "kind": "ContainerizedWorkload", + "metadata": { + "name": "poc5" + }, + "spec": { + "containers": [{ + "image": "nginx:1.9.4", + "name": "poc5", + "ports": [{ + "containerPort": 80, + "name": "default", + "protocol": "TCP" + }] + }] + } + } + }, + "Traits": [{ + "trait": { + "apiVersion": "core.oam.dev/v1alpha2", + "kind": "ManualScalerTrait", + "metadata": { + "annotations": { + "vela.oam.dev/traitDef": "scale" + } + }, + "spec": { + "replicaCount": 2 + } + } + }] + } +} +``` +### DELETE /api/envs/:envName/apps/:appName (app delete) + + +## Workloads +### POST /api/workloads/ (workload create) +- parameters +```go +type WorkloadRunBody struct { + EnvName string `json:"env_name"` + WorkloadType string `json:"workload_type"` + WorkloadName string `json:"workload_name"` + AppGroup string `json:"app_group,omitempty"` + Flags []CommonFlag `json:"flags"` + Staging bool `json:"staging,omitempty"` + Traits []TraitBody `json:"traits,omitempty"` +} +``` + +The parameter should in `TraitBody` format and `Trait` should be in the following format. +```go +type TraitBody struct { + EnvName string `json:"env_name"` + Name string `json:"name"` + Flags []CommonFlag `json:"flags"` + WorkloadName string `json:"workload_name"` + AppGroup string `json:"app_group,omitempty"` +} +``` + +- example +sample request +```json +{ + "env_name": "default", + "workload_type": "containerized", + "workload_name": "poc2", + "flags": [ + { + "name": "image", + "value": "nginx:1.9.4" + }, + { + "name": "port", + "value": "80" + } + ], +} +``` +sample response +```json +{ +"code": 200, +"data": "Creating App poc2 SUCCEED" +} +``` + +Please also specify `traits` values if need to attach a trait to several traits to the application during workload creation. +```json +{ + "env_name": "default", + "workload_type": "containerized", + "workload_name": "poc5", + "app_group": "", + "flags": [ + { + "name": "port", + "value": "80" + }, + { + "name": "image", + "value": "nginx:1.9.4" + } + ], + "staging": false, + "traits": [ + { + "name": "scale", + "env_name": "default", + "workload_name": "poc5", + "flags": [ + { + "name": "replica", + "value": "4" + } + ] + } + ] +} +``` + +### GET /api/workloads/:workloadName (workload description) +- example +sample response +```json +{ + "code": 200, + "data": { + "name": "containerized", + "type": "workload", + "template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind: \"ContainerizedWorkload\"\n\tmetadata: name: containerized.name\n\tspec: {\n\t\tcontainers: [{\n\t\t\timage: containerized.image\n\t\t\tname: containerized.name\n\t\t\tports: [{\n\t\t\t\tcontainerPort: containerized.port\n\t\t\t\tprotocol: \"TCP\"\n\t\t\t\tname: \"default\"\n\t\t\t}]\n\t\t}]\n\t}\n}\ncontainerized: {\n\tname: string\n\t// +usage=specify app image\n\t// +short=i\n\timage: string\n\t// +usage=specify port for container\n\t// +short=p\n\tport: *6379 | int\n}\n", + "parameters": [{ + "name": "name", + "required": true, + "default": "", + "type": 16 + }, { + "name": "image", + "short": "i", + "required": true, + "default": "", + "usage": "specify app image", + "type": 16 + }, { + "name": "port", + "short": "p", + "default": 6379, + "usage": "specify port for container", + "type": 4 + }], + "definition": "/Users/zhouzhengxi/.vela/capabilities/containerizedworkloads.core.oam.dev.cue", + "crdName": "containerizedworkloads.core.oam.dev", + "crdInfo": { + "apiVersion": "core.oam.dev/v1alpha2", + "kind": "ContainerizedWorkload" + } + } +} +``` + +### GET /api/workloads/ (workloads list) +- example +sample response +```json +{ + "code": 200, + "data": [{ + "name": "containerized", + "parameters": [{ + "name": "name", + "required": true, + "default": "", + "type": 16 + }, { + "name": "image", + "short": "i", + "required": true, + "default": "", + "usage": "specify app image", + "type": 16 + }, { + "name": "port", + "short": "p", + "default": 6379, + "usage": "specify port for container", + "type": 4 + }] + }, { + "name": "deployment", + "parameters": [{ + "name": "name", + "required": true, + "default": "", + "type": 16 + }, { + "name": "env", + "type": 128 + }, { + "name": "image", + "required": true, + "default": "", + "type": 16 + }, { + "name": "port", + "default": 8080, + "type": 4 + }] + }] +} +``` + +## Trait +### POST /envs/:envName/apps/:appName/traits/ (attach a trait) +- example +sample request +```json +{ + "name": "scale", + "flags": [ + { + "name": "replica", + "value": "4" + } + ] +} +``` +sample response +```json +{ +"code": 200, +"data": "Succeeded!" +} +``` +### GET /api/traits/:traitName (trait description) +- example +sample response +```json +{ + "code": 200, + "data": { + "name": "manualscaler", + "type": "trait", + "template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind: \"ManualScalerTrait\"\n\tspec: {\n\t\treplicaCount: manualscaler.replica\n\t}\n}\nmanualscaler: {\n\t//+short=r\n\treplica: *2 | int\n}\n", + "parameters": [{ + "name": "replica", + "short": "r", + "default": 2, + "type": 4 + }], + "definition": "/Users/zhouzhengxi/.vela/capabilities/manualscalertraits.core.oam.dev.cue", + "crdName": "manualscalertraits.core.oam.dev", + "appliesTo": ["containerized"], + "crdInfo": { + "apiVersion": "core.oam.dev/v1alpha2", + "kind": "ManualScalerTrait" + } + } +} +``` +### GET /api/traits/ (traits list) + +- response +`applies_to` shows the workload list which the trait can be attached. + +- example +sample response +```json +{ + "code": 200, + "data": [{ + "name": "manualscaler", + "definition": "manualscalertraits.core.oam.dev", + "applies_to": ["containerized"] + }, { + "name": "rollout", + "definition": "simplerollouttraits.extend.oam.dev", + "applies_to": ["containerized", "deployment"] + }, { + "name": "scale", + "definition": "manualscalertraits.core.oam.dev", + "applies_to": ["containerized", "deployment"] + }] +} +``` + +### DELETE /envs/:envName/apps/:appName/traits/:traitName (detach a trait) +- example +sample response +```json +{"code":200,"data":"Succeeded!"} +``` + +## Capability +### GET /capability-centers/ (Capability Center list) +- example +sample response +```json +{ + "code": 200, + "data": [{ + "name": "poc", + "url": "https://github.com/wonderflow/catalog/tree/repos/repos" + }, { + "name": "abc", + "url": "http://abc.com" + }] +} +``` +### PUT /capability-centers/ (Capability Center add) +- example +sample request +```json +{"Name":"c1","Address":"https://github.com/wonderflow/catalog/tree/repos/repos"} +``` + +### PUT /capability-centers/:capabilityCenterName/capabilities/ (Capability Center sync) + +- example + - response +```json +{ +"code": 200, +"data": "sync finished" +} +``` + + +### PUT /capability-centers/:capabilityCenterName/capabilities/:capabilityName (install a capability) +- example +sample API url +`/api/capability-centers/c1/capabilities/rollout` +sample response +```json +{"code":200,"data":"Successfully installed capability rollout from c1"} +``` + +### DELETE /api/capabilities/:capabilityName (delete the capability) +- example +sample response +```json +{"code":200,"data":"containerized removed successfully"} +``` + +### GET /api/capabilities/ (capability list) +- example +sample response +```json +{ + "code": 200, + "data": [{ + "name": "containerized", + "type": "workload", + "template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind: \"ContainerizedWorkload\"\n\tmetadata: name: containerized.name\n\tspec: {\n\t\tcontainers: [{\n\t\t\timage: containerized.image\n\t\t\tname: containerized.name\n\t\t\tports: [{\n\t\t\t\tcontainerPort: containerized.port\n\t\t\t\tprotocol: \"TCP\"\n\t\t\t\tname: \"default\"\n\t\t\t}]\n\t\t}]\n\t}\n}\ncontainerized: {\n\tname: string\n\t// +usage=specify app image\n\t// +short=i\n\timage: string\n\t// +usage=specify port for container\n\t// +short=p\n\tport: *6379 | int\n}\n", + "parameters": [{ + "name": "name", + "required": true, + "default": "", + "type": 16 + }, { + "name": "image", + "short": "i", + "required": true, + "default": "", + "usage": "specify app image", + "type": 16 + }, { + "name": "port", + "short": "p", + "default": 6379, + "usage": "specify port for container", + "type": 4 + }], + "definition": "/Users/zhouzhengxi/.vela/centers/c1/.tmp/containerizedworkloads.core.oam.dev.cue", + "crdName": "containerizedworkloads.core.oam.dev", + "center": "c1", + "status": "uninstalled" + },{ + "name": "rollout", + "type": "trait", + "template": "#Template: {\n\tapiVersion: \"extend.oam.dev/v1alpha2\"\n\tkind: \"SimpleRolloutTrait\"\n\tspec: {\n\t\treplica: rollout.replica\n\t\tmaxUnavailable: rollout.maxUnavailable\n\t\tbatch: rollout.batch\n\t}\n}\nrollout: {\n\treplica: *3 | int\n\tmaxUnavailable: *1 | int\n\tbatch: *2 | int\n}\n", + "parameters": [{ + "name": "replica", + "default": 3, + "type": 4 + }, { + "name": "maxUnavailable", + "default": 1, + "type": 4 + }, { + "name": "batch", + "default": 2, + "type": 4 + }], + "definition": "/Users/zhouzhengxi/.vela/centers/poc/.tmp/simplerollouttraits.extend.oam.dev.cue", + "crdName": "simplerollouttraits.extend.oam.dev", + "center": "poc", + "appliesTo": ["containerized", "deployment"], + "status": "uninstalled" + }] +} +``` + +## Others +- applications search diff --git a/documentation/vela.md b/documentation/cli/vela.md similarity index 100% rename from documentation/vela.md rename to documentation/cli/vela.md diff --git a/documentation/vela_app_delete.md b/documentation/cli/vela_app_delete.md similarity index 100% rename from documentation/vela_app_delete.md rename to documentation/cli/vela_app_delete.md diff --git a/documentation/vela_app_ls.md b/documentation/cli/vela_app_ls.md similarity index 100% rename from documentation/vela_app_ls.md rename to documentation/cli/vela_app_ls.md diff --git a/documentation/vela_app_run.md b/documentation/cli/vela_app_run.md similarity index 100% rename from documentation/vela_app_run.md rename to documentation/cli/vela_app_run.md diff --git a/documentation/vela_app_show.md b/documentation/cli/vela_app_show.md similarity index 100% rename from documentation/vela_app_show.md rename to documentation/cli/vela_app_show.md diff --git a/documentation/vela_app_status.md b/documentation/cli/vela_app_status.md similarity index 100% rename from documentation/vela_app_status.md rename to documentation/cli/vela_app_status.md diff --git a/documentation/vela_cap_add.md b/documentation/cli/vela_cap_add.md similarity index 100% rename from documentation/vela_cap_add.md rename to documentation/cli/vela_cap_add.md diff --git a/documentation/vela_cap_center_config.md b/documentation/cli/vela_cap_center_config.md similarity index 100% rename from documentation/vela_cap_center_config.md rename to documentation/cli/vela_cap_center_config.md diff --git a/documentation/vela_cap_center_sync.md b/documentation/cli/vela_cap_center_sync.md similarity index 100% rename from documentation/vela_cap_center_sync.md rename to documentation/cli/vela_cap_center_sync.md diff --git a/documentation/vela_cap_ls.md b/documentation/cli/vela_cap_ls.md similarity index 100% rename from documentation/vela_cap_ls.md rename to documentation/cli/vela_cap_ls.md diff --git a/documentation/vela_cap_remove.md b/documentation/cli/vela_cap_remove.md similarity index 100% rename from documentation/vela_cap_remove.md rename to documentation/cli/vela_cap_remove.md diff --git a/documentation/vela_comp_run.md b/documentation/cli/vela_comp_run.md similarity index 100% rename from documentation/vela_comp_run.md rename to documentation/cli/vela_comp_run.md diff --git a/documentation/vela_completion.md b/documentation/cli/vela_completion.md similarity index 100% rename from documentation/vela_completion.md rename to documentation/cli/vela_completion.md diff --git a/documentation/vela_completion_bash.md b/documentation/cli/vela_completion_bash.md similarity index 100% rename from documentation/vela_completion_bash.md rename to documentation/cli/vela_completion_bash.md diff --git a/documentation/vela_completion_zsh.md b/documentation/cli/vela_completion_zsh.md similarity index 100% rename from documentation/vela_completion_zsh.md rename to documentation/cli/vela_completion_zsh.md diff --git a/documentation/vela_dashboard.md b/documentation/cli/vela_dashboard.md similarity index 100% rename from documentation/vela_dashboard.md rename to documentation/cli/vela_dashboard.md diff --git a/documentation/cli/vela_deployment_run.md b/documentation/cli/vela_deployment_run.md new file mode 100644 index 000000000..818c52c3d --- /dev/null +++ b/documentation/cli/vela_deployment_run.md @@ -0,0 +1,40 @@ +## vela deployment:run + +Run deployment workloads + +### Synopsis + +Run deployment workloads + +``` +vela deployment:run [args] +``` + +### Examples + +``` +vela deployment:run frontend +``` + +### Options + +``` + -a, --app string create or add into an existing application group + -h, --help help for deployment:run + --image string + --name string + --port int (default 8080) + -s, --staging only save changes locally without real update application +``` + +### Options inherited from parent commands + +``` + -e, --env string specify env name for application +``` + +### SEE ALSO + +* [vela](vela.md) - ✈️ A Micro App Platform for Kubernetes. + +###### Auto generated by spf13/cobra on 17-Aug-2020 diff --git a/documentation/vela_env.md b/documentation/cli/vela_env.md similarity index 100% rename from documentation/vela_env.md rename to documentation/cli/vela_env.md diff --git a/documentation/vela_env_delete.md b/documentation/cli/vela_env_delete.md similarity index 100% rename from documentation/vela_env_delete.md rename to documentation/cli/vela_env_delete.md diff --git a/documentation/vela_env_init.md b/documentation/cli/vela_env_init.md similarity index 100% rename from documentation/vela_env_init.md rename to documentation/cli/vela_env_init.md diff --git a/documentation/vela_env_sw.md b/documentation/cli/vela_env_sw.md similarity index 100% rename from documentation/vela_env_sw.md rename to documentation/cli/vela_env_sw.md diff --git a/documentation/vela_rollout.md b/documentation/cli/vela_rollout.md similarity index 100% rename from documentation/vela_rollout.md rename to documentation/cli/vela_rollout.md diff --git a/documentation/vela_rollout_detach.md b/documentation/cli/vela_rollout_detach.md similarity index 100% rename from documentation/vela_rollout_detach.md rename to documentation/cli/vela_rollout_detach.md diff --git a/documentation/vela_scale.md b/documentation/cli/vela_scale.md similarity index 100% rename from documentation/vela_scale.md rename to documentation/cli/vela_scale.md diff --git a/documentation/vela_scale_detach.md b/documentation/cli/vela_scale_detach.md similarity index 100% rename from documentation/vela_scale_detach.md rename to documentation/cli/vela_scale_detach.md diff --git a/documentation/vela_system_info.md b/documentation/cli/vela_system_info.md similarity index 100% rename from documentation/vela_system_info.md rename to documentation/cli/vela_system_info.md diff --git a/documentation/vela_system_init.md b/documentation/cli/vela_system_init.md similarity index 100% rename from documentation/vela_system_init.md rename to documentation/cli/vela_system_init.md diff --git a/documentation/vela_system_update.md b/documentation/cli/vela_system_update.md similarity index 100% rename from documentation/vela_system_update.md rename to documentation/cli/vela_system_update.md diff --git a/documentation/vela_traits.md b/documentation/cli/vela_traits.md similarity index 100% rename from documentation/vela_traits.md rename to documentation/cli/vela_traits.md diff --git a/documentation/vela_version.md b/documentation/cli/vela_version.md similarity index 100% rename from documentation/vela_version.md rename to documentation/cli/vela_version.md diff --git a/documentation/vela_workloads.md b/documentation/cli/vela_workloads.md similarity index 100% rename from documentation/vela_workloads.md rename to documentation/cli/vela_workloads.md