Browse Source

[doc] Fix api standard error (#10292)

* fix api standard error
* add patch method
3.1.0-release
xiangzihao 3 years ago committed by GitHub
parent
commit
12a09f6d5d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 36
      docs/docs/en/development/api-standard.md
  2. 37
      docs/docs/zh/development/api-standard.md

36
docs/docs/en/development/api-standard.md

@ -20,25 +20,25 @@ Use URI to locate the resource, and use GET to indicate query.
+ When the URI is a type of resource, it means to query a type of resource. For example, the following example indicates paging query `alter-groups`.
```
Method: GET
/api/dolphinscheduler/alert-groups
/dolphinscheduler/alert-groups
```
+ When the URI is a single resource, it means to query this resource. For example, the following example means to query the specified `alter-group`.
```
Method: GET
/api/dolphinscheduler/alter-groups/{id}
/dolphinscheduler/alter-groups/{id}
```
+ In addition, we can also express query sub-resources based on URI, as follows:
```
Method: GET
/api/dolphinscheduler/projects/{projectId}/tasks
/dolphinscheduler/projects/{projectId}/tasks
```
**The above examples all represent paging query. If we need to query all data, we need to add `/list` after the URI to distinguish. Do not mix the same API for both paged query and query.**
```
Method: GET
/api/dolphinscheduler/alert-groups/list
/dolphinscheduler/alert-groups/list
```
### ② Create - POST
@ -48,13 +48,13 @@ Use URI to locate the resource, use POST to indicate create, and then return the
```
Method: POST
/api/dolphinscheduler/alter-groups
/dolphinscheduler/alter-groups
```
+ create sub-resources is also the same as above.
```
Method: POST
/api/dolphinscheduler/alter-groups/{alterGroupId}/tasks
/dolphinscheduler/alter-groups/{alterGroupId}/tasks
```
### ③ Modify - PUT
@ -62,7 +62,7 @@ Use URI to locate the resource, use PUT to indicate modify.
+ modify an `alert-group`
```
Method: PUT
/api/dolphinscheduler/alter-groups/{alterGroupId}
/dolphinscheduler/alter-groups/{alterGroupId}
```
### ④ Delete -DELETE
@ -71,20 +71,28 @@ Use URI to locate the resource, use DELETE to indicate delete.
+ delete an `alert-group`
```
Method: DELETE
/api/dolphinscheduler/alter-groups/{alterGroupId}
/dolphinscheduler/alter-groups/{alterGroupId}
```
+ batch deletion: batch delete the id array,we should use POST. **(Do not use the DELETE method, because the body of the DELETE request has no semantic meaning, and it is possible that some gateways, proxies, and firewalls will directly strip off the request body after receiving the DELETE request.)**
```
Method: POST
/api/dolphinscheduler/alter-groups/batch-delete
/dolphinscheduler/alter-groups/batch-delete
```
### ⑤ Others
### ⑤ Partial Modifications -PATCH
Use URI to locate the resource, use PATCH to partial modifications.
```
Method: PATCH
/dolphinscheduler/alter-groups/{alterGroupId}
```
### ⑥ Others
In addition to creating, deleting, modifying and quering, we also locate the corresponding resource through url, and then append operations to it after the path, such as:
```
/api/dolphinscheduler/alert-groups/verify-name
/api/dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt
/dolphinscheduler/alert-groups/verify-name
/dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt
```
## 3. Parameter design
@ -94,7 +102,7 @@ In the case of paging, if the parameter entered by the user is less than 1, the
## 4. Others design
### base URL
The URI of the project needs to use `/api/<project_name>` as the base path, so as to identify that these APIs are under this project.
The URI of the project needs to use `/<project_name>` as the base path, so as to identify that these APIs are under this project.
```
/api/dolphinscheduler
/dolphinscheduler
```

37
docs/docs/zh/development/api-standard.md

@ -23,25 +23,25 @@ Restful URI 的设计基于资源:
+ 当 URI 为一类资源时表示查询一类资源,例如下面样例表示分页查询 `alter-groups`
```
Method: GET
/api/dolphinscheduler/alert-groups
/dolphinscheduler/alert-groups
```
+ 当 URI 为单个资源时表示查询此资源,例如下面样例表示查询对应的 `alter-group`
```
Method: GET
/api/dolphinscheduler/alter-groups/{id}
/dolphinscheduler/alter-groups/{id}
```
+ 此外,我们还可以根据 URI 来表示查询子资源,如下:
```
Method: GET
/api/dolphinscheduler/projects/{projectId}/tasks
/dolphinscheduler/projects/{projectId}/tasks
```
**上述的关于查询的方式都表示分页查询,如果我们需要查询全部数据的话,则需在 URI 的后面加 `/list` 来区分。分页查询和查询全部不要混用一个 API。**
```
Method: GET
/api/dolphinscheduler/alert-groups/list
/dolphinscheduler/alert-groups/list
```
### ② 创建操作 - POST
@ -51,20 +51,20 @@ Method: GET
```
Method: POST
/api/dolphinscheduler/alter-groups
/dolphinscheduler/alter-groups
```
+ 创建子资源也是类似的操作:
```
Method: POST
/api/dolphinscheduler/alter-groups/{alterGroupId}/tasks
/dolphinscheduler/alter-groups/{alterGroupId}/tasks
```
### ③ 修改操作 - PUT
通过 URI 来定位某一资源,通过 PUT 指定对其修改。
```
Method: PUT
/api/dolphinscheduler/alter-groups/{alterGroupId}
/dolphinscheduler/alter-groups/{alterGroupId}
```
### ④ 删除操作 -DELETE
@ -73,20 +73,29 @@ Method: PUT
+ 下面例子表示删除 `alterGroupId` 对应的资源:
```
Method: DELETE
/api/dolphinscheduler/alter-groups/{alterGroupId}
/dolphinscheduler/alter-groups/{alterGroupId}
```
+ 批量删除:对传入的 id 数组进行批量删除,使用 POST 方法。**(这里不要用 DELETE 方法,因为 DELETE 请求的 body 在语义上没有任何意义,而且有可能一些网关,代理,防火墙在收到 DELETE 请求后会把请求的 body 直接剥离掉。)**
```
Method: POST
/api/dolphinscheduler/alter-groups/batch-delete
/dolphinscheduler/alter-groups/batch-delete
```
### ⑤ 其他操作
### ⑤ 部分更新操作 -PATCH
通过 URI 来定位某一资源,通过 PATCH 指定对其部分更新。
+ 下面例子表示部分更新 `alterGroupId` 对应的资源:
```
Method: PATCH
/dolphinscheduler/alter-groups/{alterGroupId}
```
### ⑥ 其他操作
除增删改查外的操作,我们同样也通过 `url` 定位到对应的资源,然后再在路径后面追加对其进行的操作。例如:
```
/api/dolphinscheduler/alert-groups/verify-name
/api/dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt
/dolphinscheduler/alert-groups/verify-name
/dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt
```
## 3. 参数设计
@ -96,7 +105,7 @@ Method: POST
## 4. 其他设计
### 基础路径
整个项目的 URI 需要以 `/api/<project_name>` 作为基础路径,从而标识这类 API 都是项目下的,即:
整个项目的 URI 需要以 `/<project_name>` 作为基础路径,从而标识这类 API 都是项目下的,即:
```
/api/dolphinscheduler
/dolphinscheduler
```
Loading…
Cancel
Save