github
/
DolphinScheduler
mirror of https://gitee.com/dolphinscheduler/DolphinScheduler.git
1
0
Fork 0
Code Issues Releases Wiki Activity
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
8d26d4fe72
commit
12a09f6d5d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 45 additions and 28 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  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
Unescape View File

@ -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`. + 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 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`. + 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 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: + In addition, we can also express query sub-resources based on URI, as follows:
``` ```
Method: GET 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.** **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 Method: GET
/api/dolphinscheduler/alert-groups/list /dolphinscheduler/alert-groups/list
``` ```
### ② Create - POST ### ② Create - POST
@ -48,13 +48,13 @@ Use URI to locate the resource, use POST to indicate create, and then return the
``` ```
Method: POST Method: POST
/api/dolphinscheduler/alter-groups /dolphinscheduler/alter-groups
``` ```
+ create sub-resources is also the same as above. + create sub-resources is also the same as above.
``` ```
Method: POST Method: POST
/api/dolphinscheduler/alter-groups/{alterGroupId}/tasks /dolphinscheduler/alter-groups/{alterGroupId}/tasks
``` ```
### ③ Modify - PUT ### ③ Modify - PUT
@ -62,7 +62,7 @@ Use URI to locate the resource, use PUT to indicate modify.
+ modify an `alert-group` + modify an `alert-group`
``` ```
Method: PUT Method: PUT
/api/dolphinscheduler/alter-groups/{alterGroupId} /dolphinscheduler/alter-groups/{alterGroupId}
``` ```
### ④ Delete -DELETE ### ④ Delete -DELETE
@ -71,20 +71,28 @@ Use URI to locate the resource, use DELETE to indicate delete.
+ delete an `alert-group` + delete an `alert-group`
``` ```
Method: DELETE 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.）** + 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 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: 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 /dolphinscheduler/alert-groups/verify-name
/api/dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt /dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt
``` ```
## 3. Parameter design ## 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 ## 4. Others design
### base URL ### 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
Unescape View File

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