Changes to asm_api-ref from docs/doc-exports#1171 (ASM API initial version 20240

Reviewed-by: Eotvos, Oliver <oliver.eotvos@t-systems.com>
Co-authored-by: OpenTelekomCloud Proposal Bot <proposalbot@otc-service.com>
Co-committed-by: OpenTelekomCloud Proposal Bot <proposalbot@otc-service.com>

api-ref/source/api/index.rst

@@ -0,0 +1,14 @@
+:original_name: asm_api_0012.html
+
+.. _asm_api_0012:
+
+API
+===
+
+-  :ref:`Service Mesh APIs <asm_api_0100>`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden: 
+
+   service_mesh_apis/index

api-ref/source/api/service_mesh_apis/index.rst

@@ -0,0 +1,20 @@
+:original_name: asm_api_0100.html
+
+.. _asm_api_0100:
+
+Service Mesh APIs
+=================
+
+-  :ref:`Creating a Service Mesh <asm_api_0101>`
+-  :ref:`Deleting a Service Mesh <asm_api_0102>`
+-  :ref:`Querying a Service Mesh <asm_api_0103>`
+-  :ref:`Querying the Service Mesh List <asm_api_0104>`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden: 
+
+   creating_a_service_mesh
+   deleting_a_service_mesh
+   querying_a_service_mesh
+   querying_the_service_mesh_list

api-ref/source/api_usage_guidelines.rst

@@ -0,0 +1,12 @@
+:original_name: asm_api_0027.html
+
+.. _asm_api_0027:
+
+API Usage Guidelines
+====================
+
+Public cloud APIs comply with the RESTful API design principles. REST-based web services are organized into resources. Each resource is identified by one or more Uniform Resource Identifiers (URIs). An application accesses a resource based on the resource's Uniform Resource Locator (URL). A URL is usually in the following format: *https://Endpoint/URI*. In the URL, **uri** indicates the resource path, that is, the API access path.
+
+Public cloud APIs use HTTPS as the transmission protocol. Requests/Responses are transmitted by using JSON messages, with media type represented by **application/json**.
+
+For details about how to use APIs, see `API Usage Guidelines <https://docs.otc.t-systems.com/en-us/api/apiug/apig-en-api-180328001.html?tag=API%20Documents>`__.

api-ref/source/appendix/error_codes.rst

@@ -0,0 +1,45 @@
+:original_name: asm_api_0018.html
+
+.. _asm_api_0018:
+
+Error Codes
+===========
+
+If an API fails to be called, no service data will be returned. You can identify the cause based on the error code of each API. If an error occurs in API calling, HTTP status code 4\ *xx* or 5\ *xx* will be returned. The response body contains the specific error code and information.
+
+Error Response Body Format
+--------------------------
+
+If an error occurs during API calling, an error code and a message will be displayed. The following shows an error response body.
+
+.. code-block::
+
+   {
+       "errorMsg": Modify the request body based on the returned message and the ASM API documentation, or contact technical support.
+       "errorCode": "ASM.01400001"
+   }
+
+In the preceding information, **error_code** indicates an error code, and **error_msg** describes the error.
+
+Error Code Description
+----------------------
+
+.. table:: **Table 1** Error codes
+
+   +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+
+   | Status Code | Error Code   | Error Message                      | Description                                | Troubleshooting                                                                                                    |
+   +=============+==============+====================================+============================================+====================================================================================================================+
+   | 400         | ASM.01400001 | Invalid request.                   | The request body is invalid.               | Modify the request body based on the returned message and the ASM API documentation, or contact technical support. |
+   +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+
+   | 401         | ASM.01401001 | Authorization failed.              | The authentication failed.                 | See the returned message or contact technical support.                                                             |
+   +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+
+   | 403         | ASM.01403001 | Forbidden.                         | The access is denied.                      | See the returned message or contact technical support.                                                             |
+   +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+
+   | 404         | ASM.01404001 | Resource not found.                | The resource is not found.                 | Check whether the resource to be accessed has been deleted.                                                        |
+   +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+
+   | 409         | ASM.01409001 | The resource already exists.       | The resource already exists.               | Delete the resource and try again.                                                                                 |
+   +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+
+   | 429         | ASM.01429001 | Resource locked by other requests. | The resource is locked by another request. | See the returned message or contact technical support.                                                             |
+   +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+
+   | 500         | ASM.01500001 | Internal error.                    | An internal error occurred.                | See the returned message or contact technical support.                                                             |
+   +-------------+--------------+------------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------------------------------------+

api-ref/source/appendix/index.rst

@@ -0,0 +1,18 @@
+:original_name: asm_api_0016.html
+
+.. _asm_api_0016:
+
+Appendix
+========
+
+-  :ref:`Status Codes <asm_api_0017>`
+-  :ref:`Error Codes <asm_api_0018>`
+-  :ref:`Obtaining a Project ID <asm_api_0019>`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden: 
+
+   status_codes
+   error_codes
+   obtaining_a_project_id

api-ref/source/appendix/obtaining_a_project_id.rst

@@ -0,0 +1,51 @@
+:original_name: asm_api_0019.html
+
+.. _asm_api_0019:
+
+Obtaining a Project ID
+======================
+
+Obtaining a Project ID by Calling an API
+----------------------------------------
+
+A project ID can be obtained by calling a specific API. For details, see `Querying Project Information Based on the Specified Criteria <https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845625.html>`__.
+
+The API used to obtain a project ID is **GET https://**\ *{Endpoint}*\ **/v3/projects/**, where *{Endpoint}* indicates the IAM endpoint. You can obtain the IAM endpoint from `Regions and Endpoints <https://docs.otc.t-systems.com/en-us/endpoint/index.html>`__.
+
+In the following example, **id** indicates the project ID.
+
+.. code-block::
+
+   {
+       "projects": [
+           {
+               "domain_id": "65382450e8f64ac0870cd180d14e684b",
+               "is_domain": false,
+               "parent_id": "65382450e8f64ac0870cd180d14e684b",
+               "name": "eu-de",
+               "description": "",
+               "links": {
+                   "next": null,
+                   "previous": null,
+                   "self": "https://www.example.com/v3/projects/a4a5d4098fb4474fa22cd05f897d6b99"
+               },
+               "id": "a4a5d4098fb4474fa22cd05f897d6b99",
+               "enabled": true
+           }
+       ],
+       "links": {
+           "next": null,
+           "previous": null,
+           "self": "https://www.example.com/v3/projects"
+       }
+   }
+
+Obtaining a Project ID from the Console
+---------------------------------------
+
+A project ID is required for some URLs when an API is called. To obtain a project ID, perform the following operations:
+
+#. Log in to the management console.
+#. Click the username and select **My Credentials** from the drop-down list. On the **API Credentials** page, view the project ID in the project list.
+
+If a project contains multiple sub-projects, click the plus (+) sign to view sub-project IDs.

api-ref/source/change_history.rst

@@ -0,0 +1,19 @@
+:original_name: asm_api_0021.html
+
+.. _asm_api_0021:
+
+Change History
+==============
+
++-----------------------------------+------------------------------------------------------------------+
+| Release On                        | Description                                                      |
++===================================+==================================================================+
+| 2025-03-07                        | Deleted duplicate links in :ref:`API <asm_api_0012>`.            |
++-----------------------------------+------------------------------------------------------------------+
+| 2024-12-11                        | Based on review comments, this document is optimized as follows: |
+|                                   |                                                                  |
+|                                   | -  Modified the API parameters.                                  |
+|                                   | -  Added response examples.                                      |
++-----------------------------------+------------------------------------------------------------------+
+| 2024-10-25                        | First release.                                                   |
++-----------------------------------+------------------------------------------------------------------+

api-ref/source/docutils.conf

@@ -0,0 +1,2 @@
+[html writers]
+table-style: table, caption-top

api-ref/source/index.rst

@@ -1,3 +1,11 @@
-========================================================
+========================================
-Welcome to the documentation of application-service-mesh
+Application Service Mesh - API Reference
-========================================================
+========================================
+
+.. toctree::
+   :maxdepth: 1
+
+   api_usage_guidelines
+   api/index
+   appendix/index
+   change_history