github.com/oam-dev/kubevela@v1.9.11/design/vela-core/restful-interface.md (about) 1 # Vela RESTful API design 2 3 Below, I list the Vela backend RESTful API grouped by each resource. 4 5 The first version does not use authentication or authorization. We will use go structure to 6 represent request and response body. 7 8 ## Common properties 9 10 ### Base URL 11 The base URL should be **`vela.oam.dev`** but in our first version, we assumed that it's `localhost`. 12 13 ### Common Request Headers 14 Below are the common request headers. All fields are required. 15 16 | Name | Type | Values | Description | 17 |---------------|--------|--------------|----------------------| 18 | x-oam-version | String | "2020-08-15" | The REST API version that user wants to use| 19 | x-oam-client-type| String | "CLI", "Dashboard" | The type of client | 20 | x-oam-request-timestamp | String | yyyy-MM-dd HH:mm:ss.SS | UTC time of the request| 21 | x-oam-client-id | String | N/A | The unique client id | 22 | x-oam-client-request-id|String| N/A | The unique client request id | 23 24 ### Common Response Headers 25 26 Name | Type | Values | Description | 27 |---------------|--------|--------------|----------------------| 28 | x-oam-client-request-id|String| N/A | The unique client request id | 29 | x-oam-response-timestamp | String | yyyy-MM-dd HH:mm:ss.SS | UTC time of the response| 30 31 32 ### Common Error Status 33 | Error code | HTTP status code | User message | 34 |----------------------------|------------------|------------------------------------------------------------------------------------| 35 | Already Exists | 409 | The specific resource already exists | 36 | Not Found | 404 | The specific resource not found | 37 | InvalidHeaderValue | 400 | The value provided for one of the HTTP headers was not in the correct format. | 38 | InvalidQueryParameterValue | 400 | An invalid value was specified for one of the query parameters in the request URI. | 39 | InvalidInput | 400 | One of the request inputs is not valid. | 40 | InternalError | 500 | The server encountered an internal error. Please retry the request. | 41 42 ### Common Query parameters 43 **updateMode** 44 ```go 45 type updateMode string 46 const fullcontent updateMode = "fullContent" 47 const cueTemplate updateMode = "cueTemplate" 48 ``` 49 50 **qureyMode** 51 ```go 52 type qureyMode string 53 const fullcontent qureyMode = "fullContent" 54 const cueTemplate qureyMode = "cueTemplate" 55 ``` 56 57 ## Environment related API 58 Environment is a top level resource in the REST API. 59 ### Create 60 **URL** : `/api/envs` 61 62 **Method** : `POST` 63 64 **Query Parameter** : `None` 65 66 **Body** : 67 68 ```go 69 type env struct { 70 envName string `json:"envName"` 71 namespace string `json:"namespace"` 72 } 73 ``` 74 75 **Responses Body** : None 76 77 ### Get 78 **URL** : `/api/envs/${envName}` 79 80 **Method** : `GET` 81 82 **Query Parameter** : `None` 83 84 **Body** : 85 ```go 86 type env struct { 87 namespace string `json:"namespace"` 88 } 89 ``` 90 91 **Responses Body** : `None` 92 93 ### List 94 **URL** : `/api/envs` 95 96 **Method** : `GET` 97 98 **Query Parameter** : `None` 99 100 **Body** : None 101 102 **Responses Body** : 103 ```go 104 type env struct { 105 envNames []string `json:"envNames"` 106 } 107 ``` 108 109 ### Delete 110 **URL** : `/api/envs/${envName}` 111 112 **Method** : `Delete` 113 114 **Query Parameter** : `None` 115 116 **Body** : `None` 117 118 **Responses Body** : `None` 119 120 ## ApplicationConfiguration related API 121 An app has to have an environment, so it is a sub-resource under an env. 122 123 ### Create 124 **URL** : `/api/envs/${envName}/apps` 125 126 **Method** : `POST` 127 128 **Query Parameter** : `appCreateMode` 129 ```go 130 type appCreateMode string 131 const fullcontent appCreateMode = "parameters" 132 const cueTemplate appCreateMode = "appFile" 133 ``` 134 135 **Body** : 136 ```go 137 type appConfigValue struct { 138 appName string `json:"appName"` 139 definition runtime.RawExtension `json:"definition"` // the content 140 definitionName string `json:"definitionName"` // use to find the definition 141 definitionType string `json:"definitionType"` 142 } 143 ``` 144 145 **Responses Body** : None 146 147 148 ### Update 149 **URL** : `/api/envs/${envName}/apps/${appName}` 150 151 **Method** : `PUT` 152 153 **Query Parameter** : `appUpdateMode` 154 ```go 155 type appUpdateMode string 156 const fullcontent appUpdateMode = "parameters" 157 const cueTemplate appUpdateMode = "appFile" 158 ``` 159 **Body** : 160 161 ```go 162 163 type appConfigValue struct { 164 definition runtime.RawExtension `json:"definition"` // the content 165 } 166 ``` 167 168 **Responses Body** : None 169 170 ### Get 171 172 **URL** : `/api/envs/${envName}/apps/${appName}` 173 174 **Method** : `Get` 175 176 **Query Parameter** : `appQuerymode` 177 ```go 178 type appQuerymode string 179 const fullcontent appQuerymode = "fullContent" 180 const parameterOnly appQuerymode = "parameterDef" 181 const statusOnly appQuerymode = "appFile" 182 const statusOnly appQuerymode = "statusOnly" 183 ``` 184 **Body** : None 185 186 **Responses Body** : 187 ```go 188 type appConfigValue struct { 189 appName string `json:"appName"` // the app name 190 definition runtime.RawExtension `json:"definition"` // the definition 191 } 192 ``` 193 194 ### List 195 196 **URL** : `/api/envs/${envName}/apps` 197 198 **Method** : `Get` 199 200 **Query Parameter** : `None` 201 202 **Body** : None 203 204 **Responses Body** : 205 ```go 206 type appConfigNames struct { 207 appConfigName string[] `json:"appConfigName"` // the appconfig name list, no next Token 208 } 209 ``` 210 211 ### Delete 212 213 **URL** : `/api/envs/${envName}/apps/${appName}` 214 215 **Method** : `Delete` 216 217 **Query Parameter** : `dryrun` 218 219 **Body** : None 220 221 **Responses Body** : None 222 223 ## Definition related API 224 225 We will add ${definitionType} in the path to differentiate if it's a workload/trait/scope definition. 226 It can be either "workloadDefinition","traitDefinition", or "scopeDefinition" as they are three different 227 types of resources. 228 229 ### Create 230 231 **URL** : `/api/${definitionType}` 232 233 **Method** : `POST` 234 235 **Query Parameter** : `None` 236 237 **Body** : 238 239 ```go 240 241 type oamDefinition struct { 242 definitionName string `json:"definitionName"` 243 definition runtime.RawExtension `json:"definition"` // the real definition data 244 } 245 ``` 246 247 ### Update 248 249 **URL** : `/api/${definitionType}/${definitionName}` 250 251 **Method** : `PUT` 252 253 **Query Parameter** : `updateMode` 254 255 **Body** : 256 257 ```go 258 259 type oamDefinition struct { 260 definition runtime.RawExtension `json:"definition"` // the definition data 261 } 262 ``` 263 264 **Responses Body** : None 265 266 ### GET 267 268 **URL** : `/api/${definitionType}/${definitionName}` 269 270 **Method** : `Get` 271 272 **Query Parameter** : `qureyMode` 273 274 **Body** : None 275 276 **Responses Body** : 277 ```go 278 type definition struct { 279 definition runtime.RawExtension `json:"definition"` // either the full definition or the cueTemplate 280 } 281 ``` 282 283 ### List 284 285 **URL** : `/api/${definitionType}` 286 287 **Method** : `Get` 288 289 **Query Parameter** : `None` 290 291 **Body** : None 292 293 **Responses Body** : 294 ```go 295 type definitionName struct { 296 definitionNames string[] `json:"definitionNames"` // the definition name list, no next Token 297 } 298 ``` 299 300 ### Delete 301 302 **URL** : `/api/${definitionType}/${definitionName}` 303 304 **Method** : `Delete` 305 306 **Query Parameter** : `dryrun` 307 308 **Body** : None 309 310 **Responses Body** : None 311 312 313 ## Repo related API 314 These API operate on definition files stored in a git repo. It could be a git repo on the local file system. 315 316 The only valid `categoryName` are `workload`,`trait` and `scope` 317 318 They all have a `repoURL` query parameter that stores the git repo's URL so that the server is stateless. 319 320 ### Update 321 322 **URL** : `/api/category/${categoryName}/${definitionName}` 323 324 **Method** : `PUT` 325 326 **Query Parameter** : `repoURL`, `updateMode` 327 328 **Body** : 329 330 ```go 331 332 type oamDefinition struct { 333 definition runtime.RawExtension `json:"definition"` // the definition data 334 } 335 ``` 336 337 **Responses Body** : None 338 339 ### GET 340 341 **URL** : `/api/category/${categoryName}/${definitionName}` 342 343 **Method** : `Get` 344 345 **Query Parameter** : `repoURL`, `qureyMode` 346 347 **Body** : None 348 349 **Responses Body** : 350 ```go 351 type definition struct { 352 definition runtime.RawExtension `json:"definition"` // either the full definition or the cueTemplate 353 } 354 ``` 355 356 ### List 357 358 **URL** : `/api/category/${categoryName}` 359 360 **Method** : `Get` 361 362 **Query Parameter** : `repoURL`, `None` 363 364 **Body** : None 365 366 **Responses Body** : 367 ```go 368 type definitionName struct { 369 definitionNames string[] `json:"definitionNames"` // the definition name list, no next Token 370 } 371 ``` 372 373 ## Version API 374 This is debatable, we are not sure if this is really needed. 375 376 ### GET 377 378 **URL** : `/api/version` 379 380 **Method** : `Get` 381 382 **Query Parameter** : None 383 384 **Body** : None 385 386 **Responses Body** : 387 ```go 388 type definition struct { 389 velaServerVersion string `json:"velaServerVersion"` 390 k8sServerVersion string `json:"k8sServerVersion"` 391 } 392 ```