To help the OpenHarmony ecosystem develop and evolve in a healthy and orderly way, this Charter defines the governance process and lifecycle (creation, change, deprecation, and deletion) of OpenHarmony APIs. It also specifies basic design requirements of OpenHarmony APIs.
To help the OpenHarmony ecosystem develop and evolve in a healthy and orderly way, this Charter defines the governance process and lifecycle (create, change, deprecate, and delete) of OpenHarmony APIs. It also specifies basic design requirements of OpenHarmony APIs.
This Charter is formulated by the API SIG and approved by the PMC for release. Any revision to this Charter will be released only after being reviewed by the API SIG and approved by the PMC.
This Charter is formulated by the [API SIG](https://www.openharmony.cn/SIG/api/) and approved by the [PMC](https://www.openharmony.cn/community/pmc/) for release. Any revision to this Charter will be released only after being reviewed by the API SIG and approved by the PMC.
## Overview
...
...
@@ -12,23 +12,23 @@ This Charter is formulated by the API SIG and approved by the PMC for release. A
The OpenHarmony software stack contains multiple roles. Naturally, OpenHarmony APIs have multiple types.
<imgsrc="figures/API-Category.png"width="800"/>
Different types of APIs have different compatibility requirements, as described in the table below.
| Type | Prepared By | Used By | Compatibility Requirement | Guarding Method |
|--- |--- |--- |--- |--- |
| Public API | System and framework | All application developers | Five API versions | X test suite (XTS) |
| Test API | Test framework | All application developers | Three API versions | To be built |
| System API | System and framework |System application developers |Not guaranteed | To be built |
| HDI | HDF | System services | Four API versions | XTS |
| Driver API | HDF | Driver developers | Not guaranteed | None |
| Inner API | System parts | System parts | Not guaranteed | None |
| Type| Prepared By| Used By| Compatibility Requirement| Guarding Method|
|---|---|---|---|---|
| Public API | System and framework| All application developers| 5 API versions| X test suite (XTS)|
| Test API | Test framework | All application developers| 3 API versions| To be built|
| System API | System and framework|System application developers|Not guaranteed| To be built|
| HDI | HDF| System services| 4 API versions| X test suite (XTS)|
| Driver API | HDF | Driver developers| Not guaranteed| None|
| Inner API | System parts| System parts| Not guaranteed| None|
The APIs are described as follows:
* Public API: APIs provided for all application developers.
* Test API: APIs provided for developers to test their applications.
* Test API: APIs used for testing. They can be used only in the test phase.
* System API: APIs provided for privileged system applications. Common applications cannot use these APIs.
* HDI: APIs that describe hardware capabilities.
* Driver API: APIs provided for driver developers.
...
...
@@ -41,6 +41,7 @@ OpenHarmony aims to build a next-generation Operating System (OS) for the Intern
* C/C++
* JavaScript
* TypeScript
* ArkTS
The content described in this Charter is irrelevant to the programming language in use. Regardless of the programming language, APIs must comply with this Charter while meeting the programming language requirements.
...
...
@@ -48,25 +49,25 @@ The content described in this Charter is irrelevant to the programming language
### Roles and Responsibilities
| Role | Responsibilities in API Governance |
| --- | --- |
| Contributor | Commit API code and design documents. |
| Committer | Review the code and submit a pre-review comment on an API commit. |
| Domain SIG | Comment on the commits of new API code, so the passed commits can be merged. <br/>Submit a pre-review comment on updated API code. |
| API SIG | Comment on updated API code. |
| PMC | Release API version plans. Review amendments of this Charter, revise the terms, and publish this Charter. |
|**Role**|**Responsibilities in API Governance**|
| - | - |
|Contributor|Commit API code and design documents.|
|Committer|Review the code and submit a pre-review comment on an API commit.|
|Domain SIG| Comment on the commits of new API code, so the passed commits can be merged.<br>Provide pre-review comments on updated API code.|
|API SIG|Comment on updated API code.|
|PMC|Release API version plans. Review amendments of this Charter, revise the terms, and publish this Charter.|
### API Review Process
The API review process is as follows:
<imgsrc="figures/API-Workflow.png"width="800"/>
The main process is as follows:
1. Initiate API review and commit code (contributor). If any APIs are added or modified, the contributor must additionally submit an API review application to specify the API requirement source, usage scenario, permission design, and privacy protection design. For details, see "API Review Application Composites" below. To avoid rework, the contributor can send an email to submit the API design document to the committer, domain SIG, and API SIG for pre-review before the formal API review application and code commit.
1. Review code (committer). After the code review is approved, the committer should submit the APIs to the domain SIG. If the API code involves multiple domains, they should be submitted to the committers of the corresponding domains. The next review step can be performed only after all committers review and approve the code.
1. Review APIs (domain SIG). The code of new APIs can be merged only after being reviewed and approved by the domain SIG. If there are changes to existing APIs, the domain SIG should submit them to the API SIG. If the new APIs involve multiple domains, they should be submitted to the SIGs of the corresponding domains. The code can be merged after being reviewed and approved by one of the domain SIGs. If the changed APIs involve multiple domains, they should be submitted to the SIGs of the corresponding domains. The next review step can be performed only after all domain SIGs approve the APIs.
1. Review API changes (API SIG). The code of changed APIs can be merged only after being reviewed and approved by the API SIG.
1. Review API changes (owner: API SIG): The code of changed APIs can be merged only after being reviewed and approved by the API SIG.
1. The review is complete.
### API Review Application Composites
...
...
@@ -87,75 +88,11 @@ For changed APIs, except the preceding operations, you must:
2. (Mandatory) Describe the change impact, substitute APIs, and corresponding application adaptation solution.
3. (Mandatory) Update the ChangeLog file. Update the API-diff file (Mandatory if JS or native API changes are involved.)
## API Design Requirements
### Consistency
1. Concept: Scenario-based service models must be abstracted to form coherent, consistent, and self-consistent OpenHarmony user program models and service concepts.
1. Term: Service terms must be nouns. Multiple nouns with similar semantic meanings are not allowed to represent the same service object. Similarly, to avoid confusion, it is not allowed to use the same noun or linguistically close nouns for different service objects.
1. Operation: Every operation action must be expressed using a unique verb.
1. Parameter sequence: The location and sequence of the same parameter or parameter sequence in multiple APIs must be the same.
1. Mechanism and algorithm: The communication mechanism, calling mode, authentication mechanism, and encryption algorithm must be consistent.
1. API reference, demo, and template style: The layout and usage must be consistent.
### Ease to Use
Design APIs from the perspective of their users rather than providers.
1. Readability: API naming and features must be easy to understand.
1. Ease of use: Provide easy-to-use APIs by reducing unnecessary coupling between APIs, avoiding dependencies on the calling sequence of multiple unrelated APIs, and avoiding calling multiple methods from different packages, modules, or classes at the same time when using a single feature.
1. Avoiding misleading: Provide capabilities complying with user expectations to avoid misuse.
1. Provide required API reference documents.
### Naming
1. Be able to express the capabilities clearly. Use full descriptive words.
1. Avoid misleading. Misleading names are more harmful than ill-stated ones.
1. Use words with clear meaning. Do not use words with common meanings, such as info, data, and object.
1. The larger the scope is, the more precise the naming should be.
1. Eliminate or minimize the use of abbreviations. Common terms in the industry must comply with industry conventions and can be abbreviated.
3. If external open-source code is referenced, retain the original bundle name, module name, or namespace, or replace the bundle name according to the preceding rules.
1. The bundle name, module name, and namespace must contain 2 to 4 segments. One word is recommended for each segment, and a maximum of two words are allowed.
1. The class name, method name, function name, member variable, and variable name cannot exceed four words.
### Permission Control
1. Completeness: All behaviors across application sandboxes must be limited by permission control.
1. Optimal granularity: One permission protects only one type of object. Developers only need to apply for one permission to access an interface.
1. Clearness: The protected object, permission scope, and sensitivity level must be clearly specified in the permission definition.
1. Minimum scope: A permission is assigned only to applications that have service requirements to minimize permission scope.
### Privacy Protection
1. The response returned from API calling should contain only necessary information.
1. Mobile phone users' personal data cannot be obtained through API calling unless required permissions are assigned by users.
1. In case that an API is called by multiple applications, if personal data needs to be disclosed to the API to be called, the caller must specify the disclosed data type, data receiver, and data use purpose in the privacy statement.
1. When an API needs to access sensitive user data (such as phone calls, contacts, and media content), the system picker mechanism must be used to prevent the API from accessing the data through sensitive permission application.
1. API openness does not allow unrelated features.
### Documentation
1. The API reference document must be written in English.
1. The API reference document must include the brief and detailed descriptions of modules and packages.
1. The API reference document must include brief descriptions of classes, methods, interfaces, enumerations, and member variables.
1. The API reference document can optionally include detailed descriptions of classes, methods, interfaces, enumerations, and member variables.
1. The API reference document must contain descriptions of all input parameters of every method or interface.
1. If a method or interface has a return value, the API reference document must contain a return value description.
1. If an exception may be thrown during the execution, the API reference document must contain the exception description.
1. The starting version of the API (annotated with @since) must be included.
1. The version of a module or class (annotated with @version) is optionally included.
1. If incompatible API changes are involved, both API-Diff and ChangeLog files must be delivered.
### Compatibility
1. The API compatibility requirements in descending order are as follows: contract compatibility > binary-code compatibility > source-code compatibility.
1. Source-code compatibility: After version evolution, the existing source code can be compiled properly.
1. Binary-code compatibility: After version evolution, the existing programs can be linked to and run properly without recompilation.
1. Contract compatibility: also called semantic compatibility. After version evolution, the original program behaviors remain unchanged.
1. API backward compatibility must meet binary-code compatibility requirements. Exceptions must be reviewed by the API SIG and approved by the PMC. Common API changes that break binary-code compatibility include:
1. Delete any API elements.
1. Reduce the visibility of a method. For example, change from protected to private or from public to protected.
1. Change the class type. For example, change from an abstract class to a non-abstract class, or from an interface class to a non-interface class.
1. Change the method prototype. For example, change the return value type, input parameter sequence, or input parameter type.
1. Change the member attributes. For example, change the member attribute from non-final to final or from non-static to static.
1. Do not modify APIs with the same prototype but incompatible features. You can modify APIs by deprecating old APIs and adding new ones with restrictions.
1. Depending on the release type, the API lifecycle and compatibility requirements are as follows:
## API Lifecycle and Compatibility Requirements
OpenHarmony APIs will evolve in the form of API versions. Each version goes through the release period shown in the following figure,
which also demonstrates the compatibility requirements for the APIs in different periods.
...
...
@@ -163,7 +100,7 @@ Design APIs from the perspective of their users rather than providers.
1. Canary versions are compatible with the previous Release version.
1. Different Canary versions of the same API version are not required to keep compatible.
1. Beta version: publicly released beta version, which cannot ensure API stability.
1.Beta versions are compatible with the previous Release version.
1.Canary versions are compatible with the previous Release version.
1. Beta versions are not compatible with the early Canary versions of the same API version.
1. Different Beta versions of the same API version are not required to keep compatible.
1. The APIs are frozen after the API Stable version is released. API additions or changes are not allowed for later Beta versions.
...
...
@@ -173,33 +110,6 @@ Design APIs from the perspective of their users rather than providers.
1. Provide substitute APIs.
1. Retain the deprecated APIs in at least five API versions released since the deprecation.
### Performance
1. Respond in a timely manner to avoid callers waiting. If an API call takes a long time, use an asynchronous API.
2. Make sure that the impact of API call timing and frequency on the RAM usage is under control.
3. Make sure that the impact of API call timing and frequency on the power consumption is under control.
4. Resources must be released in a timely manner when APIs that use resources are called. A fault tolerance mechanism must be provided for abnormal scenarios to ensure timely resource release.
### Power Consumption
1. Evaluate the impact of the API call timing and frequency on power consumption, and optimize the design if there is any impact.
2. Make sure that the power consumption does not deteriorate during version evolution.
### Reliability
1. APIs shall not crash due to external input (such as input parameters, system status, and external data), internal status, or data exceptions. It must return a specific error code or throw a predefined exception.
2. It must be specified whether an API is called synchronously or asynchronously. If an API is called synchronously, specify the timeout duration or allow the caller to set the timeout duration to prevent service response failure caused by call suspension.
3. APIs must support multi-thread reentrant.
4. APIs must meet the idempotence requirement, which means that the same effect should be obtained for one or multiple API call requests with the same service meaning (except that API call depends on external resource changes). For reentrant API call, avoid introducing time-varying factors, such as system ticks, static variables, and global variables without mutual exclusion protection. For repeated call of the same client, **contextID**, **clientToken**, and **sequenceNo** can be used as input parameters.
5. The lifecycle of objects created in APIs must have an end to prevent object resource leakage.
6. The APIs must specify the maximum number of retries allowed after a call failure.
### Testing
1. Automatic API test cases must be delivered for all new APIs.
2. Use a test case for each single scenario. One test case covers a single function of an API, simplifying the code logic of each single test case.
3. The test case execution must be efficient. The execution time of each test case must be limited to milliseconds.
4. Automatic API test cases must be available for all APIs.
5. Assertions with functional logic are required in addition to the capability of throwing exceptions.
### Programming Languages
### API Design Specifications
Regardless of the programming language in use, APIs must comply with the OpenHarmony programming language specifications.
For details, see [OpenHarmony API Design Specifications](OpenHarmony-API-quality.md).
| v0.1| OpenHarmony API SIG | November 2022| Trial version.|
## Purpose
An API is a definition provided by a software implementer for developers on the programming UI to reflect the capability scope of a software entity.
The quality of APIs greatly affects developer experience.
To deliver a sound developer experience and promote the healthy development of the OpenHarmony ecosystem, the API SIG formulates the OpenHarmony API design specifications.
## Scope
OpenHarmony APIs are classified into public APIs (open to third-party applications) and system APIs (available only for system applications).
The design specifications are effective for both types of APIs, regardless of the programming language in use.
For details about the API classification, see [OpenHarmony API Governance Charter](OpenHarmony-API-governance.md).
## API Design Objectives
A good API design must meet the following requirements:
* Operational: An API must be able to implement the capability it claims to offer. This is the fundamental requirement.
* Expressive: By calling an API, the caller can clearly express what they want to do.
* Simple: An API must be easy to learn and use, and not prone to errors.
* Predictable: An API must always complete its mission according to the definition. If the definition does not contain errors or exceptions, no error or exception should occur regardless of how many times the API is called. If an error or a failure may occur, describe the error or failure in the definition and return the corresponding error at the correct time.
You must understand the following when designing APIs:
* The stability and consistency of APIs take precedence over the API quantity.
* A better API name is the one that is easy to understand, not a shorter one.
* APIs should be encapsulated to prevent too much information from being exposed.
From the perspective of developers, a well-designed API has different features in different phrases.
* In the learning phase
* Easy to understand
* Easy to use
* In the development phase
* Expressive
* Simple
* Predictable
* In the maintenance phase
* Stable
* Easy to maintain
## API Design Overview
To make the rules as universal as possible, the specifications do not involve programming language differences or coding specifications. You need to comply with the corresponding requirements for them.
This document provides pre-release review specifications and post-release evaluation specifications.
* The pre-release review specifications are the basic requirements for APIs. Any API must meet these requirements before passing the release review.
* The post-release evaluation specifications require the API providers to keep an eye on the APIs after they are published. Even though an API has met all the pre-release review specifications, it may not be perfect. On-time review after the release helps further improve the API quality.
The following lists all the rules that you should comply with during API design. The list is provided for quick indexing, and the detailed description is provided in the following sections.
Every OpenHarmony API provider should be familiar with these rules.
### Pre-release Review Specifications
* Usability
* Rule 1: Coding rules compliant
* Rule 2: Grammatically correct
* Rule 3: Proper use of abbreviations
* Rule 4: Accurate use of words in pairs
* Rule 5: Accurate use of design or architecture patterns
* Rule 34: Basic descriptions for modules, namespaces, classes, and functions
* Rule 35: Clear description of use cases
* Rule 36: Accurate API description
* Rule 37: Accurate parameter description
* Rule 38: Accurate return value/exception description
* Rule 39: Complete meta information
* Rule 40: Consistent style
* Organization mode
* Rule 41: Reasonable layering
* Rule 42: Proper module division
* Rule 43: API reference document available (as part of the API)
* Quality related
* Rule 44: Performance requirements met
* Rule 45: Proper power consumption
* Rule 46: Testable
* Rule 47: Environmentally adaptable
### Post-release Evaluation Specifications
* Stability
* Rule 48: Minimized rate for deprecated or changed APIs
* Security
* Rule 49: No abuse of APIs
* Rule 50: No exploitation of APIs
* Maintainability
* Rule 51: Evolution support
* Rule 52: Consistent behavior after feature expansion
* Rule 53: Documents updated accordingly
* Irreplaceability
* Rule 54: Orthogonal design
* Feedback from developers
* Rule 55: Developer feedback noticed
## Description of Pre-release Review Specifications
### Usability
Usability should be considered in any design. During the design of OpenHarmony APIs, consider usability from the following aspects:
#### Naming
***Rule 1: Coding rules compliant**
The definition of an API must comply with the coding rules of the project to which the API belongs, for example, the rules for uppercase and lowercase letters, underscores (_), hyphens (-), and prefixes.
You can refer to the following coding rules for the OpenHarmony project:
API names must be in English. Generally, a class is named using a noun, for example, **exampleManager**, **exampleService**, and **exampleAnimation**. A function is named using a verb or verb-object structure, for example, **start()**, **createUser()**, and **startBoot()**.
It is incorrect to name a class **Start** or a function **ball()**.
In terms of verbs, use transitive verbs, transitive verbs, and verb tenses correctly. For example, you can name events **transferStarted()** and **renderDone()**.
***Rule 3: Proper use of abbreviations**
Avoid abbreviations as much as possible, as abbreviations are difficult to understand or even cause misunderstanding.
Use only abbreviations that are well known. Do not make your own abbreviations.
***Rule 4: Accurate use of words in pairs**
Many words can be used to express the same meaning. The table below lists some examples.
| make | create, set up, build, generate, compose, add, new |
When naming APIs, try to use words in pairs, rather than any synonym.
For example, if **add** is used for an API name, **remove** is a better option than **destroy** for its counterpart; if **increase** is used, **decrease** is a better option that **reduce**.
The table below lists common words in pairs that can be used in API names.
| Word | Counterpart |
| -------- | -------- |
| add | remove |
| increase | decrease |
| open | close |
| begin | end |
| insert | delete |
| show | hide |
| create | destroy |
| lock | unlock |
| source | target |
| first | last |
| min | max |
| start | stop |
| get | set |
| next | previous |
| up | down |
| new | old |
***Rule 5: Accurate use of design or architecture patterns**
The design or architecture pattern is actually the jargon of the software industry. Use them correctly to avoid misunderstanding.
If your API contains words such as **Strategy**, **Builder**, **Factory**, and **Singleton**, make sure you understand these design patterns accurately and use them correctly.
When your API uses a specific pattern, use the terms defined in that pattern. Do not change the world class or sequence.
***Rule 6: No controversial names**
Do not use controversial names, including but not limited to any words that violate the laws and regulations, cause religious disputes, or lead to racial discrimination, as well as dirty words.
Considering that OpenHarmony is designed to empower a variety of industries, you need to pay more attention when deciding whether a name is controversial.
#### Parameters
***Rule 7: Appropriate parameter types**
Typically, it is better to use class type parameters than simple type parameters.
For example, the following APIs seem to be fine at first glance:
*`addPerson(string id, string name, int age)`
*`removePerson(string id, string name, int age)`
*`modifyPerson(string id, string name, int age)`
However, they are not friendly for expansion. If you define the parameters using the class type **Person**, it would be easy to add new parameters. What's more, you do not need to make any changes to the APIs.
Class type parameters reduce the parameter quantity in an API, thereby making the API easy to be remembered.
***Rule 8: Appropriate parameter quantity**
Use 7 or less parameters in an API. In most cases, use 3 to 5 parameters in an API, for easy of use.
The number of parameters in an API should not exceed 10 in any case. If an API contains more than 10 parameters, the possible cause is that the type is not well encapsulated or the API implementation logic is too complex. If this is the case, consider to use another form.
***Rule 9: Appropriate parameter sequence**
In some programming languages, parameters in an API are often organized in the order of input parameters followed by output parameters.
If you further sort the parameters based on their logical relationship and importance, it is easier for developers to memorize and use the parameters.
You should place optional parameters after mandatory parameters, and place callback functions at the end. For example, in the **fs.readFile** API, the **path** parameter is mandatory, and **encoding** and **flag** have default values.
```js
fs.readFile(path[,options],callback)
```
```js
fs.readFile('/etc/passwd',(err,data)=>{
if(err)throwerr;
console.log(data);
});
fs.readFile('/etc/passwd',{
encoding:'utf-8',
flag:'r+'
},(err,data)=>{
if(err)throwerr;
console.log(data);
});
```
#### Return Values
***Rule 10: Complete return value definition**
The definition of return values must be complete. This means that you need to consider exceptions in addition to normal situations so developers will be able to handle the exceptions.
Example:
* For a return value of the number type, define the value range and the situation in which an extreme value occurs.
* For a return value of the Boolean type, define when **true** and **false** will be returned.
* For a return value of the array or set type, define when **null** or an empty set will be returned.
* For a return value of the enum type, define when each enumerated value will be returned.
***Rule 11: Appropriate exception definition**
An exception is returned when, for example, an input parameter is invalid or the API implementation logic is incorrect.
For the same module or service, there should be a unified definition for the situations in which an error value will be returned and an exception will be thrown.
In addition, the same exception type should be used for the same exception.
Consistency greatly reduces the difficulty in using the API and the probability of errors.
#### Others
You are advised to adhere to the following rules to make your APIs easy to use.
***Rule 12: Positive expressions**
Positive expressions enable developers to think less.
When naming APIs, use positive words instead of negative ones.
Most API use errors are caused by parameter passing errors.
For example, for the following function, both the second and third parameters are Boolean values. When calling the function, developers may find it difficult to remember the parameter values correctly.
The use of enums instead of Boolean values and integers helps reduce the possibility of API use errors.
Combining multiple parameters into a type also reduces the possibility of parameter passing errors.
***Rule 14: No sequential coupling**
Ensure high cohesion and low coupling during software design, especially for large projects.
Coupling indicates the dependency between software modules. A too deep coupling often means a poor architecture design.
According to the static software structure or hierarchical architecture diagram, if there are few dependencies between modules but obvious API calling directions between upper and lower layers, it is a good design. On the contrary, if there are complex inter-module dependencies or call chains with opposite directions between the upper and lower layers, the structure is poor.
Among all the types of coupling, sequential coupling must be noted for APIs. Sequential coupling means that the APIs in a class must be called in a specific sequence in order to work properly.
The following is an example of sequential coupling:
```js
doSomethingFirst()
doSomethingSecond()
doSomethingThird()
```
Sequential coupling poses high requirements on the callers and is prone to incorrect use.
To avoid sequential coupling, you can use the **template method** design pattern.
***Rule 15: Accurate logic expression**
Some APIs, for example, **getUserAccount()**, are used to query information, whereas others, for example, **createUserAccount()**, are used to modify data.
Never use an API that seems to be used for query to carry out data modification. It will confuse developers.
The name of an API should express everything it does, with no concealing. Only in this way can it be easier for developers to understand what the API does when reading the code.
If an API implements too many features and cannot be named in a few words, it usually means that you should split the API into multiple APIs, to make it cohesive enough.
Do not assume that developers have the same background information as you do.
For example, you may name a field **language** and believe all the readers know that you are talking about the programming language. In fact, someone might wonder whether you are talking about the language of speech. Name it **programmingLanuage** will eliminate the misunderstanding.
However, do not go to another extreme. If the class name or namespace name contains a prefix, do not repeat it in the function.
***Rule 16: Encapsulation welcomed**
Encapsulation is a key concept in object-oriented programming.
Encapsulation means that system capabilities should be encapsulated as simple APIs, with implementation details hidden as much as possible.
It is like an iceberg. No matter how large the portion submerged in water is, the visible portion above water should be small enough and concise enough. This is a user-friendly interface.
Encapsulation makes it easy for developers to use, while making fewer errors. For example, an electronic engineer connects all the electric wires in the room and leaves only one button to users. This is a good encapsulation. It prevents users from the need to understand the complex circuit structure and protect them from electric shocks.
***Rule 17: Single responsibility**
An API should try to do only one thing (a single core responsibility) as much as possible. Example:
```js
// Not recommended
view.fetchDataAndRender(url,templete);
// Recommended
letdata=view.dataManager.fetchData(url);
view.render(data,templete);
```
Single responsibility enables developers to use APIs in the minimum unit as required. It also enables developers to encapsulate the service logic based on their service requirements.
In some cases, the rule "single responsibility" may conflict with "encapsulation welcomed". For example, if there are many APIs with a single capability, developers have to notice the calling details for each API.
If this is the case, determine the level of the capability provided by your API based on the encapsulation level. To provide the capability for a high-level caller, you can encapsulate the APIs. To provide the capability for a low-level caller, you can provide separate APIs.
### Availability
***Rule 18: Reliability**
The APIs provided by the operating system must be fully reliable.
Reliability does not mean that every call has to be successful. If resources are used up, providing a proper return value or exception is also an implementation of reliability.
For every API, all the possible situations must be accurately defined, and the work should be completed according to the defined behavior in the corresponding situation.
Unreliable behavior includes failure to return a value as scheduled or causing application exceptions for no reason.
***Rule 19: Complete functionalities**
When planning a feature or capability, consider the completeness of functionalities. For example, a process should not be interrupted or an option should not be missing within the supported scope. This requires you to perform sufficient verification and deduction when designing the APIs.
Even if the comprehensive features of an operating system are gradually provided through a series of iterations across years, every specific version should provide closed and self-consistent capabilities. To achieve this goal, you must define clear boundaries for each iteration.
***Rule 20: Permission and privacy protection**
Permission control and data protection must be provided for any API that involves user data or user privacy.
Comply with the following principles for permission control:
1. Completeness: All behaviors across application sandboxes must be limited by permission control.
2. Optimal granularity: One permission protects only one type of object. Developers only need to apply for the permission of the minimum granularity to access an API.
3. Clearness: The protected object, permission scope, and sensitivity level must be clearly specified in the permission definition.
4. Minimum scope: A permission is assigned only to applications that have service requirements.
Comply with the following principles for privacy protection:
1. The return value should contain only necessary information.
2. The API calling should not obtain or collect users' personal data, unless required permissions are assigned by users.
3. In case that an API is called by multiple applications, if personal data needs to be disclosed to the callee, the caller must specify the disclosed data type, data receiver, and data use purpose in the privacy statement.
4. When an API needs to access sensitive user data (such as calls, contacts, and media content), the system picker mechanism must be used to prevent the API from accessing the data through sensitive permission application.
5. Open APIs should not contain unrelated features.
***Rule 21: Concurrent environment**
The OpenHarmony APIs do not require all threads to be safe, considering the extremely high cost (for example, program complexity and performance impact). You only need to select the APIs as required.
APIs dedicated for concurrent environments must be properly designed and described.
In the internal implementation of an API, thread safety issues should be solved as much as possible.
***Rule 22: Resource management closure**
If an API requests dynamic resources, resource release should also be considered.
If the requested resources are returned to the caller, an API must be provided for the caller to release the resources.
If the requested resources are not directly returned to the caller, consider the resource lifecycle and release timing in the API.
If there is an upper limit for resource usage, describe it clearly and provide an API to check whether the upper limit is reached.
Pay special attention to the time for releasing exclusive resources.
***Rule 23: Retry logic**
For APIs that may encounter calling failures, provide a retry mechanism. For example, for the scenario in which a process cannot obtain an exclusive resource (such as camera) that is already occupied by another, provide an API to query whether the resource is available.
To prevent repeated attempts, you can provide a listener.
Specify the maximum number of retries allowed after the API call failure.
***Rule 24: Idempotence requirements**
In mathematics, the idempotent function expression is **f(x) = f(f(x))**. For example, the function for calculating the absolute value, that is, **abs(x) = abs(abs(x))**, is idempotent.
In computer science, idempotence indicates that one or more requests for a resource should have the same effect.
From the perspective of APIs, the effect of calling the API once to open a file should be the same as the effect of calling the API multiple times to open the file. Similarly, the effect of calling the API once to close a file should be the same as the effect of calling the API multiple times to close the file.
***Rule 25: Device universality**
OpenHarmony is designed for various types of devices.
The API design should meet the device universality requirements. Example:
* For UI components, consider the size of different screens.
* For data storage, consider the size of different storage devices.
* For user input events, consider different user interaction modes, such as touches, voice, and keys.
Certain APIs are available only for specific devices. Example:
* Health sensor APIs are available only for wearables.
* Vehicle control APIs are available only for telematics devices.
You can calibrate the API application scenarios by referring to [SysCap](../application-dev/quick-start/syscap.md).
### Consistency
***Rule 26: Consistent terms and concepts**
For purposes of easy understanding, use consistent terms and concepts in API names and descriptions. Avoid jargon. Abstract scenario-specific service models to form coherent and consistent OpenHarmony concepts.
In this regard, observe the following principles:
1. Use a single term for each concept.
2. Terms should be appropriate, explainable, and easy to understand.
4. The definition of terms should be accurate and unambiguous.
5. Common terms in the industry should not be redefined and should be used by following the industry practices.
In general, use terms already defined in [OpenHarmony Glossary](../glossary.md). If necessary, you can add terms to the glossary.
***Rule 27: Consistent inter-device behavior**
By default, an API should behavior the same between devices of different types.
If the behavior will be different because of the device types, clearly describe the differences and provide a check mechanism.
***Rule 28: Consistent version evolution**
By default, every API should provide consistent behavior in different versions. If an API change will cause behavior incompatibility, the minimum requirement is to distinguish the target version of the applications.
Simply speaking, API behavior changes should not affect developed applications.
***Rule 29: Consistent naming style**
Accurate API names do not always mean consistency. For example, words with similar meanings, such as **picture** and **image**, and **path** and **URL**, are often seen in the same set of APIs. You should use the same name when referring to the same object.
For example, the following APIs, which are used to obtain media assets, have different naming styles:
The same parameter sequence should be used for APIs in the same namespace or module.
For example, there is no restriction on the sequence of **deviceId** and **missionId** in a single API, but their sequence in the APIs of a module must be the same.
If both synchronous and asynchronous APIs are provided, you can add the suffix **Sync** to the synchronization API name for better distinguishing. Example:
```js
functiongetDefaultDisplaySync():Display;
```
If only the synchronization API is provided and the return value is not **void**, you do not need to add the suffix. Example:
Carry out full planning and all-round consideration at the very beginning, since API changes pose a high cost. However, you must notice that API changes are inevitable during system development.
API changes must be backward compatible. After an API is deprecated, mark the API **deprecated** in the source code and reference document, and provide the new counterpart.
Retain the deprecated APIs in at least five API versions released since the deprecation. After five versions, you can delete the deprecated APIs after providing obvious notifications to developers and leaving sufficient time for them to modify the applications.
***Rule 33: Backward binary-code compatibility**
Binary-code compatibility means that an existing program can be linked to and run properly without recompilation after version evolution. It ensures that the memory layout of an instance does not change in the case of a version update.
Common C++ API changes that cause binary-code incompatibility include:
1. Deleting any API elements
2. Adding a virtual function
3. Changing the inheritance of a class
4. Changing the declaration sequence of virtual functions
5. Adding a non-static member variable
6. Changing the declaration sequence of non-static member variables
In terms of binary-code compatibility, C APIs have inherent advantages over C++ APIs. Therefore, you are advised to define native APIs using C.
### API References
API references are used to carry API information. Their quality is vital for the ecosystem development.
***Rule 34: Basic descriptions for modules, namespaces, classes, and functions**
A basic description must be provided for each module, namespace, class, and function.
A detailed description must be provided for key modules and complex modules.
The description should be in English.
***Rule 35: Clear description of use cases**
Sample code must be provided for all APIs, and common application scenarios must be covered.
A detailed application scenario description should be provided for complex APIs. You can provide a link to the tutorial that exhibits how to use the API.
***Rule 36: Accurate API description**
There should be no typos in the API description.
All code samples must be able to run properly. If the behavior of an API varies in different versions, describe the differences.
Mark deprecated APIs and provide the counterparts.
***Rule 37: Accurate parameter description**
Each parameter in an API must be clearly described. Example:
* For a non-simple type, specify whether the parameter can be null.
* For an enum type, describe the use case of each enumerated value.
* For an optional parameter, specify when the caller needs to pass the parameter and when to ignore the parameter.
**Rule 38: Accurate return value/exception description**
If an API has a return value or an exception, describe them in the API reference. Example:
```js
/**
* Sync function of rename.
* @param {string} path - path.
* @returns {void} rmdir success.
* @throws {BusinessError} 401 - if type of path is not string.
* @throws {BusinessError} 201 - if permission denied.
The API reference must contain basic meta information, such as **@syscap** and **@since**.
The meta information describes the basic information about an API. The tool and SDK will use the information to perform corresponding processing, for example, displaying a message for a deprecated API.
***Rule 40: Consistent style**
The API reference document must use consistent style, for example, bold text and image colors.
### Organization Mode
***Rule 41: Reasonable layering**
An operating system is usually structured in a hierarchical model, and each layer solves different levels of problems.
You need to consider layering during API design.
For example, in the construction industry, all buildings have walls and doors, the walls are made of bricks, and the doors are made of wood. There are abstract layers as follows:
* The first layer is raw materials, including cement, sand, and wood.
* The second layer is building elements constructed from raw materials. Examples of building elements are doors, windows, and walls.
* The third floor is the type of room, for example, bedroom, bathroom, and living room.
* The top floor is a variety of buildings for different purposes, such as hotels and apartments.
Each layer has its own concepts to consider and problems to solve. Think carefully about the layer that your API targets.
***Rule 42: Proper module division**
In addition to horizontal layering, you should pay attention to vertical layering, that is, module division. OpenHarmony APIs are organized in the form of namespaces. A namespace usually corresponds to a module.
A smaller subsystem can provide only one namespace and have all the APIs in this namespace. A large subsystem can provide multiple namespaces.
***Rule 43: API reference document available (as part of the API)**
When talking about the APIs provided for developers, we mean not only programming interfaces, but also anything that can be exposed.
The API reference document is one that exposed. It should be managed according to the same rules as the APIs.
### Quality Related
***Rule 44: Performance requirements met**
The APIs provided by an operating system may be used by all upper-layer applications. They must meet performance requirements in practice.
The following lists some requirements:
1. Respond in a timely manner to avoid callers waiting. If an API call takes a long time, use an asynchronous API.
2. Use the shared memory and message queue when a large amount of data needs to be transmitted.
3. Minimize the number of new process entities.
4. Release resources in a timely manner. A fault tolerance mechanism must be provided for abnormal scenarios to ensure timely resource release.
***Rule 45: Proper power consumption**
OpenHarmony was designed for different types of devices, most of which were passive devices. Therefore, power consumption must be considered during API design.
During the implementation of each function or mechanism, consider power consumption. Provide a detailed description for high power consumption APIs and offer guidance on how to use them.
Provide a mechanism to prevent APIs from consuming power heavily. For example, after the device screen is locked or the application is switched to the background, stop the high power consumption behavior.
Ensure that power consumption does not deteriorate during version evolution.
***Rule 46: Testable**
Provide complete automatic test cases to:
1. Quick detect faults during API development to improve API quality.
2. Ensure that code modification does not affect existing functionalities during version iteration.
3. Ensure backward compatibility of APIs.
An OpenHarmony API must meet the following requirements:
1. Automatic API test cases must be delivered for all new APIs.
2. Use a test case for each single scenario. One test case covers a single functionality of an API, simplifying the code logic of each single test case.
3. The test case execution must be efficient. The execution time of each test case must be limited to milliseconds.
4. Automatic API test cases must be available for all APIs.
5. Assertions with functional logic are required in addition to the capability of throwing exceptions.
***Rule 47: Environmentally adaptable**
To support user personality features, an operating system usually provides environment customization capabilities, such as language, light/dark theme, and font size.
For related APIs, if developers do not pass specified parameters, the results in the corresponding environment should be returned based on the environment in use.
## Description of Post-Release Evaluation Specifications
Even though all the pre-release rules have been satisfied, some issues might be detected during API use.
It does not mean that these issues do not need to be considered during API design.
On the contrary, you should carry out full considerations during the design to prevent these issues from occurring after the API release.
If issues related to the following rules occur after the API release, the API quality is not good.
### Stability
***Rule 48: Minimized rate for deprecated or changed APIs**
For an API, stability is the most important attribute.
API deprecation and behavior changes greatly reduce maintenance efficiency of developers, especially when multiple device types and system versions are involved.
Designing an API with long-term stability and continuous compatibility is the goal of every API designer.
The API deprecation rate and change rate are inversely proportional to the API quality to some extent.
### Security
***Rule 49: No abuse of APIs**
All APIs should be designed to prevent themselves from being abused. Abuse means that the use of an API exceeds the expected limit, either in quantity or scope.
For example, the capability for accessing user data (such as **Gallery** and **Contacts**) or running in the background for a long time may be abused.
To prevent abuse in terms of quantity, use one-time authorization.
To prevent abuse in terms of scope, perform restrictions based on the caller identity.
No matter what mechanism is used, describe it in the API reference. In the case of excessive abuse, notify the caller through a specific return value.
***Rule 50: No exploitation of APIs**
Exploitation means that the use of an API causes negative impact, for example, system attacks.
If a system problem occurs when an API or a combination of APIs is called, regardless of how they are called, there are defects in the API.
It is forbidden if an API (in any case) can be called to crash the system, prevent the system from working, or steal user data. You should consider all possible calling scenarios to avoid extreme situations.
### Maintainability
***Rule 51: Evolution support**
A large feature of the operating system may take years to complete. This requires you to consider scalability during API design.
If a group of new APIs are added to the new version and the original APIs are deprecated, the API design is poor. This situation should be avoided.
***Rule 52: Consistent behavior after feature expansion**
With the system evolution, it is common that new parameters are added to APIs or new options are added to parameters.
It is important to keep API behavior consistent. The original behavior should not be damaged by the introduction of new scenarios.
If the behavior has to be changed, only the applications using the new version provide the new behavior. The behavior of applications using the old version remains unchanged.
***Rule 53: Documents updated accordingly**
When updating the API implementation, update the API reference document accordingly. From the perspective of compatibility, the original behavior should not be changed. New functionalities should be implemented by new APIs.
However, you can change the behavior of an existing API in the following cases:
1. The change is made to rectify the defect.
2. The change is made to improve performance or reduce power consumption.
3. The change is made to provide new features or scenarios, without affecting the original feature or scenario logic.
Describe the first and second cases in the Release Notes, and describe the third case in the API reference document.
### Irreplaceability
***Rule 54: Orthogonal design**
Orthogonality means that APIs should not overlap.
For example, if an API provides the capability of creating a user account, whereas another API provides the capability of creating a user and logging in to the system, the orthogonality rule is not satisfied. You can change the logic of the second API so it provides the login capability only.
If you draw API capabilities one by one, there should be no overlap between these graphs. For APIs at the same layer, it is not allowed that an API provides capabilities A, B, and C, whereas another API provides capabilities B, C, and D.
To facilitate invocation, some APIs can be combined into a higher-level API. This uses different abstraction levels, not an overlap at the same layer.
### Feedback from Developers
***Rule 55: Developer feedback noticed**
A released API may have defects detected, even after going through the trial phase.
Therefore, you should continue to notice the feedback from developers after the API release.
The following types of feedback may be possible:
* Requirements: Developers ask for new APIs to provide capabilities. You can plan these requirements in later versions.
* Defects related to API behavior: The behavior of an API is inconsistent with that described in the reference document. This defect should be fixed as soon as possible. If the inconsistency is caused by incorrect description in the reference document, correct the document.
* Inappropriate API design: The name or parameter setting of an API has defects. In this case, develop a new API to replace the defective API.
In some cases, you may need to change the behavior of a published API. Note that behavior changes take effect only on new applications. The behavior can be determined based on the target API version of the application.
In the worst case, you may need to deprecate an existing API and use a new one.
An abstraction of a functionality that an application can provide. An ability is the minimum unit for the system to schedule applications. An application can contain one or more **Ability** instances.
The abstraction of a functionality provided by an application. **Ability** is the minimum unit for the system to schedule an application. It is a component that can implement an independent functionality. An application can contain one or more **Ability** instances. Different types of abilities are defined in the Feature Ability (FA) model and stage model.
- ### AMS
Ability Manager Service, a service that manages abilities.
- ### App pack
An application package released to the application market. The package contains one or more HAP files with the file name extension .app.
- ### App component
Same as ability. Each ability is an app component.
- ### ArkCompiler
A component-based and configurable multi-language compilation and running platform built in OpenHarmony. Bolstered by key components such as the compiler, toolchain, and runtime, ArkCompiler is able to compile and run code written in various advanced programming languages on multiple chip platforms. It also enables the OpenHarmony standard system and its applications and services to run on a variety of device types, from phones and PCs, tablets, TVs, automobiles, to smart wearables.
A component-based, configurable multi-language compilation and running platform built in OpenHarmony. Bolstered by key components such as the compiler, toolchain, and runtime, ArkCompiler is able to compile and run code written in various advanced programming languages on multiple chip platforms. It also enables the OpenHarmony standard system and its applications and services to run on a variety of device types, from phones and PCs, tablets, TVs, automobiles, to smart wearables.
- ### ArkTS
Application development language used in OpenHarmony. Based on TypeScript, ArkTS extends capabilities such as declarative UI and status management, helping you develop applications in a simpler and more natural way.
- ### ArkUI
A simplified and high-performance UI development framework for cross-device application design and development, increasing your productivity when creating application UIs for use across devices. For details, see [ArkUI Overview](application-dev/ui/arkui-overview.md).
Native UI framework of OpenHarmony. ArkUI is a simplified, high-performance UI development framework for cross-device application design and development, increasing your productivity when creating application UIs for use across devices. For details, see [ArkUI Overview](application-dev/ui/arkui-overview.md).
- ### Atomic service
A brand-new application form provided by OpenHarmony. Each atomic service has an independent entry for users to easily access, such as by tapping it, using OneHop, or scanning a particular QR code. They support silent installation (installed automatically by the system in the background).
## B
...
...
@@ -26,17 +41,29 @@
Bundle Manager Service, a service that manages application bundles.
## C
- ### C API
Native development interface provided by the OpenHarmony SDK.
- ### Continuation
Distributed operations provided by OpenHarmony, including cross-device migration and multi-device collaboration.
## D
- ### Derivative framework
A third-party framework bridged to the native framework.
- ### DevEco Device Tool
A one-stop development environment and all-in-one resource platform for smart device developers. It provides comprehensive capabilities spanning the entire process of device development, from chip template project creation and custom development resource selection to code writing, build, debugging, and burning.
- ### DMS
Distributed Management Service, a service used for distributed data management.
Distributed Management Service, a service used for distributed management.
## F
...
...
@@ -46,8 +73,7 @@
- ### FA model
Feature Ability model, one of the development models supported by the ability development framework. It is the only application development model supported by API version 8 and earlier. The FA model provides [FAs](#fa) and [Particle abilities (PAs)](#pa). The FA supports the Page ability template, and the PA supports the Service, Data, and Form ability templates. For details, see [FA Model Overview](application-dev/ability/fa-brief.md).
A development model provided by the ability framework. It is the only application development model supported by API version 8 and earlier. The FA model provides [FAs](#fa) and [Particle abilities (PAs)](#pa). The FA supports the Page ability template, and the PA supports the Service, Data, and Form ability templates. For details, see [FA Model Overview](application-dev/ability/fa-brief.md).
## H
...
...
@@ -55,9 +81,13 @@
OpenHarmony Ability Package, released with the file name extension .hap. One HAP provides all content of an application, including code, resources, third-party libraries, and an application configuration file.
- ### HAR
OpenHarmony Archive file, which contains the middle format of code, resources, and configuration files.
- ### HCS
HDF Configuration Source (HCS), providing the [Hardware Driver Foundation (HDF)](#hdf) configuration in key-value pairs. HCS removes the dependency between configuration code and driver code, simplifies configuration management.
HDF Configuration Source, providing the Hardware Driver Foundation (HDF) configuration in key-value pairs. HCS removes the dependency between configuration code and driver code, simplifying configuration management.
- ### HC-GEN
...
...
@@ -67,7 +97,7 @@
- ### HDF
Hardware Driver Foundation that provides a unified access interface for peripherals and the framework for driver development and management in OpenHarmony.
Hardware Driver Foundation, which provides a unified access interface for peripherals and the framework for driver development and management in OpenHarmony.
- ### Hypium
...
...
@@ -80,6 +110,12 @@
Intelligent Distributed Networking, a distributed networking unit of OpenHarmony. You can use IDN to obtain the device list and device states and subscribe to the connection state changes of devices on a distributed network.
## N
- ### Native framework
A development framework provided by the system. A non-native framework is a third-party framework.
## P
...
...
@@ -87,18 +123,41 @@
Particle Ability, an ability that does not have a UI in the ability framework of the FA model. It provides services and support for FAs. For example, a PA can function as a background service to provide computing power or as a data store to provide data access capabilities. The PA supports Service, Data, and Form ability templates.
## S
- ### SA
System Ability, which is a system-level component written by system developers.
- ### Secondary framework
A third-party framework that does not depend on the native framework.
- ### Stage model
A development model provided by the ability framework since API version 9. The stage model provides **UIAbility** and **ExtensionAbility** classes. The **ExtensionAbility** classes include **ServiceExtensionAbility**, **FormExtensionAbility**, **DataShareExtensionAbility**, and more.
- ### Super Virtual Device
Also called Super Device. It integrates the capabilities of multiple devices through the distributed technology into a virtual hardware resource pool and then centrally manages and schedules these capabilities based on application requirements.
- ### Stage model
- ### SysCap
A development model supported by the Ability development framework since API version 9. The stage model provides **Ability** and **ExtensionAbility** classes. The **ExtensionAbility** classes include **ServiceExtensionAbility**, **FormExtensionAbility**, **DataShareExtensionAbility**, and more.
System Capability, each relatively independent feature in OpenHarmony, such as Bluetooth, Wi-Fi, NFC, and camera. Each system capability corresponds to multiple APIs, and each API definition contains the corresponding SysCap tag.
- ### System type
- Mini system: an operating system for the devices that come with MCU processors, such as Arm Cortex-M and 32-bit RISC-V, and memory greater than or equal to 128 KiB. This system provides rich short-distance connection capabilities and peripheral access bus. The mini system applies to smart home products such as LinkIoT module devices and sensors.
- Small system: an operating system for the devices that come with application processors, such as Arm Cortex-A, and memory greater than or equal to 1 MiB. This system provides higher security capabilities, a standard graphics framework, and video encoding and decoding capabilities. The small system applies to smart home products such as IP cameras, peephole cameras, and routers as well as smart travel products such as event data recorders (EDRs).
- Standard system: an operating system for the devices that come with application processors, such as Arm Cortex-A, and memory greater than or equal to 128 MiB. This system provides a complete application framework supporting enhanced interaction, 3D GPU, hardware composer, diverse components, and rich animations. The standard system applies to high-end refrigerator displays.
- Mini system: an operating system for the devices that come with MCU processors, such as Arm Cortex-M and 32-bit RISC-V, and memory greater than or equal to 128 KiB. This system provides rich short-range connection capabilities and peripheral access bus. The mini system applies to smart home products such as LinkIoT module devices and sensors.
- Small system: an operating system for the devices that come with application processors such as Arm Cortex-A and memory greater than or equal to 1 MiB. This system provides higher security capabilities, a standard graphics framework, and video encoding and decoding capabilities. The small system applies to smart home products such as IP cameras, peephole cameras, and routers as well as easy travel products such as event data recorders (EDRs).
- Standard system: an operating system for the devices that come with application processors such as Arm Cortex-A and memory greater than or equal to 128 MiB. This system provides a complete application framework supporting enhanced interaction, 3D GPU, hardware composer, diverse components, and rich animations. The standard system applies to high-end refrigerator displays.
## U
- ### UI component
Part of the UI that supports user interaction.
## X
- ### XComponent
Component interfaces provided by ArkUI to meet self-rendering requirements of developers.
