github/kubevela
1
0
Fork 0
mirror of https://github.com/kubevela/kubevela.git synced 2026-05-21 08:43:35 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
245123679149bee8a8a2a0ec53fdf2d324b7920e
kubevela/docs/api/vela-restful-api-reference.md
Harry Zhang ec5b45a428 Init docs for kubevela 
Move non user facint things into e2e
2020-10-26 14:34:22 -07:00

730 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
{
"envName": "e2",
"namespace": "e2",
"email": "e@gmail.com",
"domain": "d.com"
}
```
sample response:
```json
{"code":200,"data":"environment e2 created, Namespace: e2, Email: e@gmail.com."}
```
### GET /api/envs/ (env list)
- Response
`current` of the elment of `data` indicates the currently using environment.
- example
sample response:
```json
{
"code": 200,
"data": [{
"envName": "ccc",
"current": "*",
"namespace": "ccc"
}, {
"envName": "default",
"namespace": "default"
}, {
"envName": "env-application",
"namespace": "env-application"
}, {
"envName": "env-hello",
"namespace": "env-hello"
}, {
"envName": "env-poc",
"namespace": "env-poc"
}, {
"envName": "env-trait",
"namespace": "env-trait"
}, {
"envName": "env-workload",
"namespace": "env-workload"
}]
}
```
### Get /api/envs/:envName (env description)
- example
sample response
```json
{"code":200,"data":[{"envName":"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 set)
- example
sample response
```json
{"code":200,"data":"Set environment succeed"}
```
```json
{"code":500,"data":"abcd not exist"}
```
### PUT /api/envs/:envName (env update)
- example
sample request:
```json
{"namespace":"ccc"}
```
sample response:
```json
{
"code": 200,
"data": "Update env succeed"
}
```
```json
{
"code":500,
"data":"env <envName> does 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": "True",
"Components": [
{
"name": "web-comp",
"Status": "True",
"workload": {
"apiVersion": "standard.oam.dev/v1alpha1",
"kind": "PodSpecWorkload",
"metadata": {
"name": "web-comp"
},
"spec": {
"podSpec": {
"containers": [
{
"image": "nginx:1.9.4",
"name": "web-comp",
"ports": [
{
"containerPort": 80,
"name": "default",
"protocol": "TCP"
}
]
}
]
},
"replicas": 1
}
},
"Traits": [
{
"trait": {
"apiVersion": "standard.oam.dev/v1alpha1",
"kind": "Route",
"metadata": {
"annotations": {
"trait.oam.dev/name": "route"
}
},
"spec": {
"backend": {
"port": 0
},
"host": "web-comp.poc.oam.dev",
"path": "",
"tls": {
"issuerName": "oam-env-default"
}
}
}
}
]
},
{
"name": "comp1",
"Status": "True",
"workload": {
"apiVersion": "standard.oam.dev/v1alpha1",
"kind": "PodSpecWorkload",
"metadata": {
"name": "comp1"
},
"spec": {
"podSpec": {
"containers": [
{
"image": "nginx:1.9.4",
"name": "comp1",
"ports": [
{
"containerPort": 6379,
"name": "default",
"protocol": "TCP"
}
]
}
]
},
"replicas": 1
}
}
}
]
}
}
```
### DELETE /api/envs/:envName/apps/:appName (app delete)
- example
sample response
```json
{
"code": 200,
"data": "delete apps succeed <appName> from <envName>"
}
```
## Components
### GET /api/envs/:envName/apps/:appName/components/:compName (component details)
- example
sample response
```json
{
"code": 200,
"data": {
"name": "web-comp",
"Status": "True",
"workload": {
"apiVersion": "standard.oam.dev/v1alpha1",
"kind": "PodSpecWorkload",
"metadata": {
"name": "web-comp"
},
"spec": {
"podSpec": {
"containers": [
{
"image": "nginx:1.9.4",
"name": "web-comp",
"ports": [
{
"containerPort": 80,
"name": "default",
"protocol": "TCP"
}
]
}
]
},
"replicas": 1
}
},
"Traits": [
{
"trait": {
"apiVersion": "standard.oam.dev/v1alpha1",
"kind": "Route",
"metadata": {
"annotations": {
"trait.oam.dev/name": "route"
}
},
"spec": {
"backend": {
"port": 0
},
"host": "web-comp.poc.oam.dev",
"path": "",
"tls": {
"issuerName": "oam-env-default"
}
}
}
}
]
}
}
```
### GET /api/envs/:envName/apps/:appName/components/ (component list)
Same as `GET /api/envs/:envName/apps/:appName (app description)`.
### DELETE /api/envs/:envName/apps/:appName/components/:compName (component delete)
- example
sample response
```
{
"code": 200,
"data": "delete apps succeed a1 from default"
}
```
## Workloads
### POST /api/workloads/ (workload create, component 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": "podspecworkload",
"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": "podspecworkload",
"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": "podspecworkload",
"type": "workload",
"template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind: \"PodSpecWorkload\"\n\tmetadata: name: podspecworkload.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": "podspecworkload",
"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/components/:compName/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": ["containerizedworkload"],
"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": ["podspecworkload"]
}, {
"name": "rollout",
"definition": "simplerollouttraits.extend.oam.dev",
"applies_to": ["podspecworkload", "deployment"]
}, {
"name": "scale",
"definition": "manualscalertraits.core.oam.dev",
"applies_to": ["podspecworkload", "deployment"]
}]
}
```
### DELETE /envs/:envName/apps/:appName/components/:compName/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"}
```
### DELETE /capability-centers/:capabilityCenterName/ (Capability Center delete)
- example
sample response
```json
{
"code": 200,
"data": "mycenter capability center removed successfully"
}
```
### 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":"podspecworkload removed successfully"}
```
### GET /api/capabilities/ (capability list)
- example
sample response
```json
{
"code": 200,
"data": [{
"name": "podspecworkload",
"type": "workload",
"template": "#Template: {\n\tapiVersion: \"core.oam.dev/v1alpha2\"\n\tkind: \"ContainerizedWorkload\"\n\tmetadata: name: podspecworkload.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": ["podspecworkload", "deployment"],
"status": "uninstalled"
}]
}
```
## Others
- applications search
Reference in New Issue View Git Blame Copy Permalink