You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dolphinscheduler.apache.org by zh...@apache.org on 2022/05/30 08:07:30 UTC
[dolphinscheduler] branch dev updated: [doc] Fix api standard error (#10292)
This is an automated email from the ASF dual-hosted git repository.
zhongjiajie pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/dolphinscheduler.git
The following commit(s) were added to refs/heads/dev by this push:
new 12a09f6d5d [doc] Fix api standard error (#10292)
12a09f6d5d is described below
commit 12a09f6d5dc6635fcfaa430dc1d45240d2d34a05
Author: xiangzihao <46...@qq.com>
AuthorDate: Mon May 30 16:07:25 2022 +0800
[doc] Fix api standard error (#10292)
* fix api standard error
* add patch method
---
docs/docs/en/development/api-standard.md | 36 +++++++++++++++++++------------
docs/docs/zh/development/api-standard.md | 37 ++++++++++++++++++++------------
2 files changed, 45 insertions(+), 28 deletions(-)
diff --git a/docs/docs/en/development/api-standard.md b/docs/docs/en/development/api-standard.md
index 7a6421cd73..61d6622165 100644
--- a/docs/docs/en/development/api-standard.md
+++ b/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
```
\ No newline at end of file
diff --git a/docs/docs/zh/development/api-standard.md b/docs/docs/zh/development/api-standard.md
index e3597608ab..0d528cea26 100644
--- a/docs/docs/zh/development/api-standard.md
+++ b/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
```
\ No newline at end of file