+不同的API类型其兼容性要求也不一样，具体如下表所述：
-为了引导OpenHarmony应用生态健康、有序发展演进，本章程对OpenHarmony API的新增、变更、废弃、删除等生命周期与治理流程进行约束，同时定义了基本的API设计要求。
+| 类型 | 提供者 | 使用者 | 兼容性要求 | 看护手段|
+|---|---|---|---|---|
+| Public API | 系统与框架 | 所有应用开发者 | 5个API版本| XTS|
+| Test API | 测试框架 | 所有应用开发者| 3个API版本| 待构建 |
+| System API | 系统与框架 |系统应用开发者 |不承诺| 待构建 |
+| HDI | HDF| 系统服务 | 4个API版本| XTS |
+| Driver API | HDF | 驱动开发者 | 不承诺 | 无 |
+| Inner API | 系统部件 | 系统部件 | 不承诺 | 无 |
-本章程由API SIG制定，经PMC批准发布；本对章程的修订必须经由API SIG评审后，由PMC批准发布。
-## API范围与定义
-应用程序接口(API)位于应用层和框架层之间，是由操作系统预定义的、由框架层和系统应用提供给应用(包括系统应用和三方应用)开发使用的类、方法等用户程序编程接口；不包括OEM扩展接口。
+各类型API说明如下：
-
+* Public API：OpenHarmony对所有应用开发者公开的API。
+* Test API：测试专用的API，供开发者使用。
+* System API：提供给系统特权应用使用的API，普通应用无法使用。
+* HDI：描述硬件能力的接口。
+* Driver API：提供给驱动开发者使用的接口。
+* Inner API：系统服务和框架实现彼此调用的API，仅供系统内部使用，不承诺兼容性。
-OpenHarmony API按可授权使用方分类包括：
-- Public API：公开发布，提供给三方应用开发使用的API。
-- System API：非公开发布，仅授权平台签名应用（signature）、预置特权应用（privileged）使用的API。
-- Test API：受限发布，仅适用于xTS或应用调试阶段可使用的API。
-如无特别说明，本章程定义的条款同时适用于Public API、System API或Test API等三种OpenHarmony API。针对System API和Test API的额外要求或例外说明，通过特别说明方式加以补充说明。
+### API与编程语言 -OpenHarmony API按编程语言分类包括： -- JS API：面向应用开放的JavaScript编程语言接口。 -- Native API：面向应用开放的C/C++编程语言接口。 -如无特别说明，本章程定义的条款同时适用于JS API和Native API。
+OpenHarmony的目标是构建面向万物互联时代的新一代操作系统，其实现涵盖但不限于以下编程语言： + +* C/C++ +* JavaScript +* TypeScript + +本章程所描述的内容与编程语言无关。即：在不违反编程语言要求的情况下，API不分编程语言都要遵守章程的要求。 ## API治理 @@ -33,24 +52,26 @@ OpenHarmony API按编程语言分类包括： | - | - | |Contributor|API的设计和交付主体，负责API相关的代码与设计文档提交。| |Committer|API相关的代码评审，涉及API提交预审。| -|领域SIG|新增API相关的代码提交评审，领域SIG评审通过即可合入。
变更API相关的代码提交预审。
| +|领域SIG| 新增API相关的代码提交评审，领域SIG评审通过即可合入。
主要过程说明：
-1. API评审申请、代码提交（Owner：Contributor），除代码提交外，如果涉及API新增或变更需同步提交相应的API设计文档，详细说明API的需求来源、场景与使用方法、权限设计、隐私保护澄清等，详见后面的API评审申请要素。为避免后续的返工，Contributor可以在正式的API评审申请、代码提交之前，先通过邮件方式将API设计文档提交Committer、领域SIG、API SIG等相关人员预审。
-1. 代码评审（Owner：Committer），代码评审和API预审，涉及API提交CodeReview通过后，还需要进一步领域SIG评审。如果单次提交同时涉及多个领域的API新增或变更，相应的API评审申请和代码需要同时提交给相关领域的Committer评审，只有所有对应领域的Committer都完成CodeReview后才能进入下一评审环节。
+
+1. API评审申请、代码提交（Owner：Contributor），所有涉及API新增或变更需同步提交相应的API评审文档，详细说明API的需求来源、场景与使用方法、权限设计、隐私保护澄清等，详见后面的API评审申请要素。为避免后续的返工，Contributor可以在正式的API评审申请、代码提交之前，先通过邮件方式将API设计文档提交Committer、领域SIG、API SIG等相关人员预审。
+1. 代码评审（Owner：Committer），代码评审和API预审，涉及API提交Code Review通过后，还需要进一步领域SIG评审。如果单次提交同时涉及多个领域的API新增或变更，相应的API评审申请和代码需要同时提交给相关领域的Committer评审，只有所有对应领域的Committer都完成CodeReview后才能进入下一评审环节。
1. API评审（Owner：领域SIG），新增API相关的代码提交评审，领域SIG评审通过即可代码合入；变更API相关的代码提交，领域SIG评审通过后，还需要进一步提交API SIG。如果单次提交同时涉及多个领域的API新增，相应的API评审申请和代码需要同时提交给相关领域的SIG评审，只需一个领域SIG评审通过即可代码合入。如果单次提交同时涉及多个领域的API变更，相应的API评审申请和代码需要同时提交给相关领域的SIG评审，只有所有对应领域的SIG都要评审通过才能进入下一评审环节。
1. API变更评审（Owner：API SIG），变更API相关的代码提交评审，评审通过即可代码。
1. 评审完成。
### API评审申请要素
-如果涉及API新增或变更需同步提交相应的API设计文档。
+
+如果涉及API新增或变更需同步提交相应的API评审文档。API评审文档使用[《OpenHarmony API 评审模板》](API-Review-Template.md)描述。
针对新增API，需要包含如下要素：
1. 需求来源与使用场景（必须）。
@@ -67,6 +88,8 @@ API评审流程如下：
3. 刷新ChangeLog（必须） 和 API-diff文档（涉及JS/Native API变更，必须）。
## API设计要求
+
+
### 一致性要求
1. 概念一致性：基于场景的业务模型抽象，形成OpenHarmony的连贯、一致、自恰的用户程序模型和业务概念。
1. 术语一致性：相应的业务术语必须采用统一名词，不允许使用多个语意接近的名词表示同一个业务对象；同样地，为了避免产生混淆，也不允许针对不同的业务对象使用相同的名词或语言接近的名词。
@@ -150,14 +173,33 @@ API评审流程如下：
1. 提供可替代接口。
1. 废弃API至少保留5个API Version版本（对废弃5个API Version的API可以彻底删除，不再支持）。
-### 性能/功耗/可靠性要求
+### 性能要求
1. 应及时响应，避免调用者等待；如果API调用执行时间过长应设计为异步方式。
-1. 应关注API调用时机、调用频次对RAM占用的影响。
-1. 应关注API调用时机、调用频次对功耗的影响。
-1. API内部创建对象的生命周期要闭合，避免对象资源泄漏。
-1. 满足幂等性要求，相同业务含义的请求API调用一次或多次重试总能获得相同的效果（API调用依赖外部资源的变化除外）。针对可重入的API调用实现内部应尽量避免引入时变因素，如系统tick、静态变量、没有互斥保护的全局变量等；针对同一客户端的多次重复调用，可以使用contextID、clientToken、squenceNo等作为调用入参。
+2. 应关注API调用时机、调用频次对RAM占用的影响。
+3. 应关注API调用时机、调用频次对功耗的影响。
+4. 对使用资源的API调用需要能及时释放资源，异常场景具备容错机制，保障资源及时释放。
+
+### 功耗要求
+
+1. 针对API调用时机、调用频次对功耗的影响做评估，有影响进行相关设计。
+2. 版本演进过程中，功耗不劣化。
+
+### 可靠性要求
+
+1. API不能因为外部输入（输入参数、系统状态、外部数据等）或者内部状态、数据异常而崩溃，应该返回确定的错误码或者抛出预定义的异常。
+2. API应明确调用是同步还是异步调用，若是同步调用，应明确超时上限或者允许调用者设置超时时间，避免调用卡死导致业务无响应。
+3. API务必支持多线程重入。
+4. 满足幂等性要求，相同业务含义的请求API调用一次或多次重试总能获得相同的效果（API调用依赖外部资源的变化除外）。针对可重入的API调用实现内部应尽量避免引入时变因素，如系统tick、静态变量、没有互斥保护的全局变量等；针对同一客户端的多次重复调用，可以使用contextID、clientToken、squenceNo等作为调用入参。
+5. API内部创建对象的生命周期要闭合，避免对象资源泄漏。
+6. API要明确客户端调用失败后，能够发起重试的最大次数。
### 测试要求
1. 新增API必须同步交付API自动化测试用例，用例100%覆盖API接口。
-1. 用例场景单一，单条用例覆盖接口单个功能场景，简化单条用例代码逻辑。
-1. 用例执行高效，每条用例执行时间控制在毫秒级。
\ No newline at end of file
+2. 用例场景单一，单条用例覆盖接口单个功能场景，简化单条用例代码逻辑。
+3. 用例执行高效，每条用例执行时间控制在毫秒级。
+4. 用例执行全自动化：接口用例需要达成100%自动化。
+5. 用例有效性：用户要求必须存在断言，且不能仅是检查是否抛出异常，需要有功能逻辑的断言。
+
+### 编程语言要求
+
+API根据其编程语言类型，需要遵守相应的OpenHarmony编程语言规范。
diff --git a/zh-cn/design/figures/API-Category.png b/zh-cn/design/figures/API-Category.png
new file mode 100644
index 0000000000000000000000000000000000000000..22813ba83cd97c5017cb79b468bdcc416886022a
Binary files /dev/null and b/zh-cn/design/figures/API-Category.png differ
diff --git a/zh-cn/design/figures/API-Definition.png b/zh-cn/design/figures/API-Definition.png
new file mode 100644
index 0000000000000000000000000000000000000000..ff0d58d643151c779ee6ef4e05e2d00794a499fb
Binary files /dev/null and b/zh-cn/design/figures/API-Definition.png differ
diff --git a/zh-cn/design/figures/API-Workflow.png b/zh-cn/design/figures/API-Workflow.png
new file mode 100644
index 0000000000000000000000000000000000000000..e65960d8bdbcb19b4f4cda4dce16a71ce229c227
Binary files /dev/null and b/zh-cn/design/figures/API-Workflow.png differ