This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/dolphinscheduler-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 39b0d4c Automated deployment: 37f22cdc5798f673613dcd3d8b890e877d3b9c77
39b0d4c is described below
commit 39b0d4c886a161f9d6e12b3682f8f1c21177b233
Author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
AuthorDate: Fri Sep 3 05:45:16 2021 +0000
Automated deployment: 37f22cdc5798f673613dcd3d8b890e877d3b9c77
---
en-us/community/development/api-standard.html | 115 ++++++++++++++++++++++++++
en-us/community/development/api-standard.json | 6 ++
zh-cn/community/development/api-standard.html | 114 +++++++++++++++++++++++++
zh-cn/community/development/api-standard.json | 6 ++
4 files changed, 241 insertions(+)
diff --git a/en-us/community/development/api-standard.html
b/en-us/community/development/api-standard.html
new file mode 100644
index 0000000..92e9654
--- /dev/null
+++ b/en-us/community/development/api-standard.html
@@ -0,0 +1,115 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0,
maximum-scale=1.0, user-scalable=no">
+ <meta name="keywords" content="api-standard">
+ <meta name="description" content="api-standard">
+ <title>api-standard</title>
+ <link rel="shortcut icon" href="/img/favicon.ico">
+ <link rel="stylesheet" href="/build/vendor.e328afe.css">
+</head>
+<body>
+ <div id="root"><div class="md2html community-page" data-reactroot=""><header
class="header-container header-container-dark"><div class="header-body"><a
href="/en-us/index.html"><img class="logo" src="/img/hlogo_white.svg"/></a><div
class="search search-dark"><span class="icon-search"></span></div><span
class="language-switch language-switch-dark">中</span><div
class="header-menu"><img class="header-menu-toggle"
src="/img/system/menu_white.png"/><div><ul class="ant-menu whiteClass ant-me
[...]
+<p>A standardized and unified API is the cornerstone of project design.The API
of DolphinScheduler follows the REST ful standard. REST ful is currently the
most popular Internet software architecture. It has a clear structure, conforms
to standards, is easy to understand and extend.</p>
+<p>This article uses the DolphinScheduler API as an example to explain how to
construct a Restful API.</p>
+<h2>1. URI design</h2>
+<p>REST is "Representational State Transfer".The design of Restful
URI is based on resources.The resource corresponds to an entity on the network,
for example: a piece of text, a picture, and a service. And each resource
corresponds to a URI.</p>
+<ul>
+<li>One Kind of Resource: expressed in the plural, such as
<code>task-instances</code>、<code>groups</code> ;</li>
+<li>A Resource: expressed in the singular, or use the ID to represent the
corresponding resource, such as
<code>group</code>、<code>groups/{groupId}</code>;</li>
+<li>Sub Resources: Resources under a certain resource, such as
<code>/instances/{instanceId}/tasks</code>;</li>
+<li>A Sub Resource：<code>/instances/{instanceId}/tasks/{taskId}</code>;</li>
+</ul>
+<h2>2. Method design</h2>
+<p>We need to locate a certain resource by URI, and then use Method or declare
actions in the path suffix to reflect the operation of the resource.</p>
+<h3>① Query - GET</h3>
+<p>Use URI to locate the resource, and use GET to indicate query.</p>
+<ul>
+<li>When the URI is a type of resource, it means to query a type of resource.
For example, the following example indicates paging query
<code>alter-groups</code>.</li>
+</ul>
+<pre><code>Method: GET
+/api/dolphinscheduler/alert-groups
+</code></pre>
+<ul>
+<li>When the URI is a single resource, it means to query this resource. For
example, the following example means to query the specified
<code>alter-group</code>.</li>
+</ul>
+<pre><code>Method: GET
+/api/dolphinscheduler/alter-groups/{id}
+</code></pre>
+<ul>
+<li>In addition, we can also express query sub-resources based on URI, as
follows:</li>
+</ul>
+<pre><code>Method: GET
+/api/dolphinscheduler/projects/{projectId}/tasks
+</code></pre>
+<p><strong>The above examples all represent paging query. If we need to query
all data, we need to add <code>/list</code> after the URI to distinguish. Do
not mix the same API for both paged query and query.</strong></p>
+<pre><code>Method: GET
+/api/dolphinscheduler/alert-groups/list
+</code></pre>
+<h3>② Create - POST</h3>
+<p>Use URI to locate the resource, use POST to indicate create, and then
return the created id to requester.</p>
+<ul>
+<li>create an <code>alter-group</code>：</li>
+</ul>
+<pre><code>Method: POST
+/api/dolphinscheduler/alter-groups
+</code></pre>
+<ul>
+<li>create sub-resources is also the same as above.</li>
+</ul>
+<pre><code>Method: POST
+/api/dolphinscheduler/alter-groups/{alterGroupId}/tasks
+</code></pre>
+<h3>③ Modify - PUT</h3>
+<p>Use URI to locate the resource, use PUT to indicate modify.</p>
+<ul>
+<li>modify an <code>alert-group</code></li>
+</ul>
+<pre><code>Method: PUT
+/api/dolphinscheduler/alter-groups/{alterGroupId}
+</code></pre>
+<h3>④ Delete -DELETE</h3>
+<p>Use URI to locate the resource, use DELETE to indicate delete.</p>
+<ul>
+<li>delete an <code>alert-group</code></li>
+</ul>
+<pre><code>Method: DELETE
+/api/dolphinscheduler/alter-groups/{alterGroupId}
+</code></pre>
+<ul>
+<li>batch deletion: batch delete the id array，we should use POST. <strong>（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.）</strong></li>
+</ul>
+<pre><code>Method: POST
+/api/dolphinscheduler/alter-groups/batch-delete
+</code></pre>
+<h3>⑤ Others</h3>
+<p>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:</p>
+<pre><code>/api/dolphinscheduler/alert-groups/verify-name
+/api/dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt
+</code></pre>
+<h2>3. Parameter design</h2>
+<p>There are two types of parameters, one is request parameter and the other
is path parameter. And the parameter must use small hump.</p>
+<p>In the case of paging, if the parameter entered by the user is less than 1,
the front end needs to automatically turn to 1, indicating that the first page
is requested; When the backend finds that the parameter entered by the user is
greater than the total number of pages, it should directly return to the last
page.</p>
+<h2>4. Others design</h2>
+<h3>base URL</h3>
+<p>The URI of the project needs to use <code>/api/<project_name></code>
as the base path, so as to identify that these APIs are under this project.</p>
+<pre><code>/api/dolphinscheduler
+</code></pre>
+</div></section><footer class="footer-container"><div
class="footer-body"><div><h3>About us</h3><h4>Do you need feedback? Please
contact us through the following ways.</h4></div><div
class="contact-container"><ul><li><img class="img-base"
src="/img/emailgray.png"/><img class="img-change" src="/img/emailblue.png"/><a
href="/en-us/community/development/subscribe.html"><p>Email
List</p></a></li><li><img class="img-base" src="/img/twittergray.png"/><img
class="img-change" src="/img/twitterbl [...]
+ <script
src="//cdn.jsdelivr.net/npm/[email protected]/dist/react-with-addons.min.js"></script>
+ <script
src="//cdn.jsdelivr.net/npm/[email protected]/dist/react-dom.min.js"></script>
+ <script>window.rootPath = '';</script>
+ <script src="/build/vendor.e26d7c6.js"></script>
+ <script src="/build/community.md.4cf7bed.js"></script>
+ <script>
+ var _hmt = _hmt || [];
+ (function() {
+ var hm = document.createElement("script");
+ hm.src = "https://hm.baidu.com/hm.js?4e7b4b400dd31fa015018a435c64d06f";;
+ var s = document.getElementsByTagName("script")[0];
+ s.parentNode.insertBefore(hm, s);
+ })();
+ </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/en-us/community/development/api-standard.json
b/en-us/community/development/api-standard.json
new file mode 100644
index 0000000..46342e9
--- /dev/null
+++ b/en-us/community/development/api-standard.json
@@ -0,0 +1,6 @@
+{
+ "filename": "api-standard.md",
+ "__html": "<h1>API design standard</h1>\n<p>A standardized and unified API
is the cornerstone of project design.The API of DolphinScheduler follows the
REST ful standard. REST ful is currently the most popular Internet software
architecture. It has a clear structure, conforms to standards, is easy to
understand and extend.</p>\n<p>This article uses the DolphinScheduler API as an
example to explain how to construct a Restful API.</p>\n<h2>1. URI
design</h2>\n<p>REST is "Representat [...]
+ "link": "/dist/en-us/community/development/api-standard.html",
+ "meta": {}
+}
\ No newline at end of file
diff --git a/zh-cn/community/development/api-standard.html
b/zh-cn/community/development/api-standard.html
new file mode 100644
index 0000000..aabb84d
--- /dev/null
+++ b/zh-cn/community/development/api-standard.html
@@ -0,0 +1,114 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0,
maximum-scale=1.0, user-scalable=no">
+ <meta name="keywords" content="api-standard">
+ <meta name="description" content="api-standard">
+ <title>api-standard</title>
+ <link rel="shortcut icon" href="/img/favicon.ico">
+ <link rel="stylesheet" href="/build/vendor.e328afe.css">
+</head>
+<body>
+ <div id="root"><div class="md2html community-page" data-reactroot=""><header
class="header-container header-container-dark"><div class="header-body"><a
href="/zh-cn/index.html"><img class="logo" src="/img/hlogo_white.svg"/></a><div
class="search search-dark"><span class="icon-search"></span></div><span
class="language-switch language-switch-dark">En</span><div
class="header-menu"><img class="header-menu-toggle"
src="/img/system/menu_white.png"/><div><ul class="ant-menu whiteClass ant-m
[...]
+<p>规范统一的 API 是项目设计的基石。DolphinScheduler 的 API 遵循 REST ful 标准，REST ful
是目前最流行的一种互联网软件架构，它结构清晰，符合标准，易于理解，扩展方便。</p>
+<p>本文以 DolphinScheduler 项目的接口为样例，讲解如何构造具有 Restful 风格的 API。</p>
+<h2>1. URI 设计</h2>
+<p>REST 即为 Representational State Transfer 的缩写，即“表现层状态转化”。</p>
+<p>“表现层”指的就是“资源”。资源对应网络上的一种实体，例如：一段文本，一张图片，一种服务。且每种资源都对应一个特定的 URI。</p>
+<p>Restful URI 的设计基于资源：</p>
+<ul>
+<li>一类资源：用复数表示，如 <code>task-instances</code>、<code>groups</code> 等；</li>
+<li>单个资源：用单数，或是用 id 值表示某类资源下的一个，如
<code>group</code>、<code>groups/{groupId}</code>；</li>
+<li>子资源：某个资源下的资源：<code>/instances/{instanceId}/tasks</code>；</li>
+<li>子资源下的单个资源：<code>/instances/{instanceId}/tasks/{taskId}</code>；</li>
+</ul>
+<h2>2. Method 设计</h2>
+<p>我们需要通过 URI 来定位某种资源，再通过 Method，或者在路径后缀声明动作来体现对资源的操作。</p>
+<h3>① 查询操作 - GET</h3>
+<p>通过 URI 来定位要资源，通过 GET 表示查询。</p>
+<ul>
+<li>当 URI 为一类资源时表示查询一类资源，例如下面样例表示分页查询 <code>alter-groups</code>。</li>
+</ul>
+<pre><code>Method: GET
+/api/dolphinscheduler/alert-groups
+</code></pre>
+<ul>
+<li>当 URI 为单个资源时表示查询此资源，例如下面样例表示查询对应的 <code>alter-group</code>。</li>
+</ul>
+<pre><code>Method: GET
+/api/dolphinscheduler/alter-groups/{id}
+</code></pre>
+<ul>
+<li>此外，我们还可以根据 URI 来表示查询子资源，如下：</li>
+</ul>
+<pre><code>Method: GET
+/api/dolphinscheduler/projects/{projectId}/tasks
+</code></pre>
+<p><strong>上述的关于查询的方式都表示分页查询，如果我们需要查询全部数据的话，则需在 URI 的后面加 <code>/list</code>
来区分。分页查询和查询全部不要混用一个 API。</strong></p>
+<pre><code>Method: GET
+/api/dolphinscheduler/alert-groups/list
+</code></pre>
+<h3>② 创建操作 - POST</h3>
+<p>通过 URI 来定位要创建的资源类型，通过 POST 表示创建动作，并且将创建后的 <code>id</code> 返回给请求者。</p>
+<ul>
+<li>下面样例表示创建一个 <code>alter-group</code>：</li>
+</ul>
+<pre><code>Method: POST
+/api/dolphinscheduler/alter-groups
+</code></pre>
+<ul>
+<li>创建子资源也是类似的操作：</li>
+</ul>
+<pre><code>Method: POST
+/api/dolphinscheduler/alter-groups/{alterGroupId}/tasks
+</code></pre>
+<h3>③ 修改操作 - PUT</h3>
+<p>通过 URI 来定位某一资源，通过 PUT 指定对其修改。</p>
+<pre><code>Method: PUT
+/api/dolphinscheduler/alter-groups/{alterGroupId}
+</code></pre>
+<h3>④ 删除操作 -DELETE</h3>
+<p>通过 URI 来定位某一资源，通过 DELETE 指定对其删除。</p>
+<ul>
+<li>下面例子表示删除 <code>alterGroupId</code> 对应的资源：</li>
+</ul>
+<pre><code>Method: DELETE
+/api/dolphinscheduler/alter-groups/{alterGroupId}
+</code></pre>
+<ul>
+<li>批量删除：对传入的 id 数组进行批量删除，使用 POST 方法。<strong>（这里不要用 DELETE 方法，因为 DELETE 请求的
body 在语义上没有任何意义，而且有可能一些网关，代理，防火墙在收到 DELETE 请求后会把请求的 body 直接剥离掉。）</strong></li>
+</ul>
+<pre><code>Method: POST
+/api/dolphinscheduler/alter-groups/batch-delete
+</code></pre>
+<h3>⑤ 其他操作</h3>
+<p>除增删改查外的操作，我们同样也通过 <code>url</code> 定位到对应的资源，然后再在路径后面追加对其进行的操作。例如：</p>
+<pre><code>/api/dolphinscheduler/alert-groups/verify-name
+/api/dolphinscheduler/projects/{projectCode}/process-instances/{code}/view-gantt
+</code></pre>
+<h2>3. 参数设计</h2>
+<p>参数分为两种，一种是请求参数(Request Param 或 Request Body)，另一种是路径参数(Path Param)。</p>
+<p>参数变量必须用小驼峰表示，并且在分页场景中，用户输入的参数小于 1，则前端需要返给后端 1
表示请求第一页；当后端发现用户输入的参数大于总页数时，直接返回最后一页。</p>
+<h2>4. 其他设计</h2>
+<h3>基础路径</h3>
+<p>整个项目的 URI 需要以 <code>/api/<project_name></code> 作为基础路径，从而标识这类 API
都是项目下的，即：</p>
+<pre><code>/api/dolphinscheduler
+</code></pre>
+</div></section><footer class="footer-container"><div
class="footer-body"><div><h3>联系我们</h3><h4>有问题需要反馈？请通过以下方式联系我们。</h4></div><div
class="contact-container"><ul><li><img class="img-base"
src="/img/emailgray.png"/><img class="img-change" src="/img/emailblue.png"/><a
href="/zh-cn/community/development/subscribe.html"><p>邮件列表</p></a></li><li><img
class="img-base" src="/img/twittergray.png"/><img class="img-change"
src="/img/twitterblue.png"/><a href="https://twitter.com/dolphinschedule";><p
[...]
+ <script
src="//cdn.jsdelivr.net/npm/[email protected]/dist/react-with-addons.min.js"></script>
+ <script
src="//cdn.jsdelivr.net/npm/[email protected]/dist/react-dom.min.js"></script>
+ <script>window.rootPath = '';</script>
+ <script src="/build/vendor.e26d7c6.js"></script>
+ <script src="/build/community.md.4cf7bed.js"></script>
+ <script>
+ var _hmt = _hmt || [];
+ (function() {
+ var hm = document.createElement("script");
+ hm.src = "https://hm.baidu.com/hm.js?4e7b4b400dd31fa015018a435c64d06f";;
+ var s = document.getElementsByTagName("script")[0];
+ s.parentNode.insertBefore(hm, s);
+ })();
+ </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/zh-cn/community/development/api-standard.json
b/zh-cn/community/development/api-standard.json
new file mode 100644
index 0000000..ab947ae
--- /dev/null
+++ b/zh-cn/community/development/api-standard.json
@@ -0,0 +1,6 @@
+{
+ "filename": "api-standard.md",
+ "__html": "<h1>API 设计规范</h1>\n<p>规范统一的 API 是项目设计的基石。DolphinScheduler 的 API
遵循 REST ful 标准，REST ful 是目前最流行的一种互联网软件架构，它结构清晰，符合标准，易于理解，扩展方便。</p>\n<p>本文以
DolphinScheduler 项目的接口为样例，讲解如何构造具有 Restful 风格的 API。</p>\n<h2>1. URI
设计</h2>\n<p>REST 即为 Representational State Transfer
的缩写，即“表现层状态转化”。</p>\n<p>“表现层”指的就是“资源”。资源对应网络上的一种实体，例如：一段文本，一张图片，一种服务。且每种资源都对应一个特定的
URI。</p>\n<p>Restful URI 的设计基于资源：</p>\n<ul>\n<li>一类资源：用复数表示，如
<code>task-instances</code>、<code>groups</code> 等；</li>\n<li>单个资源：用单数，或是用 i
[...]
+ "link": "/dist/zh-cn/community/development/api-standard.html",
+ "meta": {}
+}
\ No newline at end of file
