1# Document Description 2 3API references provide the description of APIs used for application development. This topic describes common fields in the API references to help you better use the reference document. 4 5## Version Description 6 7In API references, the earliest versions of APIs and components are specified in the following ways: 8 9- For a new API or component, the version information is provided at the beginning of the reference document. Example: "The initial APIs of this module are supported since API version 7." 10- For a new feature of an existing API or component, a superscript is added following the feature. For example, "uid<sup>8+</sup>" indicates that the **uid** attribute is supported since API version 8. 11 12## System Capability Description 13 14System capability refers to a relatively independent feature in the operating system. Different devices provide different system capabilities, and multiple APIs implement a system capability. You can determine whether an API can be used based on system capabilities. For details, see [SystemCapability](syscap.md). 15 16The following description is provided for each API in the reference document to describe the system capability of the API: "**System capability**: SystemCapability.xxx.xxx" 17 18<!--Del--> 19- You can use the [SystemCapability List](syscap-list.md) to query the devices supported by a specific capability set.<!--DelEnd--> 20- You can call the **canIUse** API to [check whether an API is available](syscap.md#checking-whether-an-api-is-available). 21- The performance of a SysCap may vary by device type. You can [check the differences between devices with a specific SysCap](syscap.md#checking-the-differences-between-devices-with-a-specific-syscap). 22<!--RP2--><!--RP2End--> 23 24<!--RP1--><!--RP1End--> 25 26## Service Widget Description 27 28A [service widget](../form/formkit-overview.md) (also called widget) is a set of UI components that display important information or operations specific to an application or atomic service. It provides users with direct access to a desired service, without the need to open the application first. 29- For APIs that can be used in ArkTS widgets, the following description will be added: "Widget capability: This API can be used in ArkTS widgets since API version *x*." 30- For APIs that cannot be used in ArkTS widgets, no special description is provided. 31 32## Permission Description 33 34By default, applications can access limited system resources. However, in some cases, an application needs to access excess data (including personal data) and functions of the system or another application to implement extended functions. For details, see [Application Permission Management Overview](../security/AccessToken/app-permission-mgmt-overview.md). 35 36To call APIs to access these resources, you must apply for the corresponding permissions by following the instructions provided in [Workflow for Requesting Permissions](../security/AccessToken/determine-application-mode.md). 37 38- If an application can call an API only after it has obtained a specific permission, the following description is provided for the API: "**Required permissions**: ohos.permission.xxxx" 39- If an application can call an API without any permission, no special description is provided. 40 41## Error Code Description 42 43You may encounter errors when using ArkTS APIs. 44 45For each API where errors might occur, you can refer to the error code section in the documentation to understand the possible error code IDs and messages for that API and handle them as needed. 46 47ArkTS API includes both asynchronous and synchronous APIs, with the following error handling methods: 48 49- For synchronous APIs, errors are uniformly thrown as exceptions, and you need to handle potential exceptions using try-catch. 50 51- For asynchronous APIs, errors may include exceptions and rejections. If you use the await/async approach, you need to handle potential exceptions and rejections using try-catch. 52 53- For asynchronous APIs using the Promise approach, errors may include exceptions and rejections. You need to handle synchronous exceptions (usually 401 exceptions) using try-catch and handle rejections using the Promise's **catch()** method or the **onrejected** callback function in the **then()** method. 54 55- For asynchronous APIs using the callback approach (not recommended), errors may include exceptions and errors returned by the callback. If you use the callback approach, you need to handle synchronous exceptions (usually 401 exceptions) using try-catch and handle errors presented through callback parameters (for example, BusinessError objects). 56 57## Application Model Description 58 59Along its evolution, the system has provided two application models: FA model and stage model. 60 61- If all the APIs of a module support only one model, the following description is provided at the beginning of the reference document: "The APIs of this module can be used only in the FA model." or "The APIs of this module can be used only in the stage model." 62- If certain APIs of a module support only one model, the following description is provided individually for these APIs: "This API can be used only in the FA model." or "This API can be used only in the stage model." 63- If both models are supported, no special description is provided. 64 65<!--Del--> 66## Available APIs 67 68Certain APIs provided by OpenHarmony are system APIs, which can be used only by original equipment manufacturers (OEMs) and cannot be used by common applications. 69 70A description regarding system APIs will be provided in the document. 71 72- If all the APIs of a module are system APIs, the following description is provided at the beginning of the reference document: "All the APIs of this module are system APIs." 73- If a specific API of a module is a system API, the following description is provided individually for the API: "This is a system API." 74 75A common application is an application whose application type is **hos_normal_app** in the HarmonyAppProvision configuration file. **hos_normal_app** is the default value for project creation. 76 77The public SDK, which does not include system APIs, is provided as standard in DevEco Studio. To use the system APIs, you must: 78 79- Switch the public SDK to the full SDK by following the instructions provided in [Switching to Full SDK](../faqs/full-sdk-switch-guide.md). 80- Change the value of **app-feature** in the HarmonyAppProvision configuration file to **hos_system_app** (indicating a system application). For details, see [HarmonyAppProvision Configuration File](../security/app-provision-structure.md). 81<!--DelEnd--> 82 83## Deprecated API Description 84 85A deprecated API is an API no longer recommended and is marked with the <sup>deprecated</sup> superscript. 86 87While deprecated APIs can still be implemented in the five API levels immediately following the version when the API is deprecated, this is not recommended. 88 89- Do not use deprecated APIs in new code. If possible, rewrite old code by replacing the deprecated APIs with their substitutes. 90- If no substitute is available, change the implementation mode by referring to the deprecation description and changelog. 91