lboka/document-database-service
1
0
Fork 0
forked from docs/document-database-service
Code Pull Requests Activity

Changes to dds_api-ref from docs/doc-exports#410 (DDS API 20221101 version

Browse Source 
DDS

Reviewed-by: Boka, Ladislav <ladislav.boka@t-systems.com>
Co-authored-by: proposalbot <proposalbot@otc-service.com>
Co-committed-by: proposalbot <proposalbot@otc-service.com>
This commit is contained in:
proposalbot 2022-11-09 23:26:45 +00:00 committed by zuul
parent addc5e4349
commit d748eab4d5
27 changed files with 2962 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
api-ref/source/_static/images/en-us_image_0208249507.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
api-ref/source/_static/images/en-us_image_0208249570.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 110 KiB

132
api-ref/source/api_calling/example.rst Normal file
View File

File diff suppressed because it is too large Load Diff

18
api-ref/source/api_calling/index.rst Normal file
View File

@ -0,0 +1,18 @@
:original_name: dds_api_0014.html
.. _dds_api_0014:
API Calling
===========
- :ref:`Scenarios <dds_api_0015>`
- :ref:`REST APIs <dds_api_0016>`
- :ref:`Example <dds_api_0017>`
.. toctree::
:maxdepth: 1
:hidden:
scenarios
rest_apis
example

120
api-ref/source/api_calling/rest_apis.rst Normal file
View File

File diff suppressed because it is too large Load Diff

20
api-ref/source/api_calling/scenarios.rst Normal file
View File

@ -0,0 +1,20 @@
:original_name: dds_api_0015.html
.. _dds_api_0015:
Scenarios
=========
DDS open APIs allow users to create, view, or delete DB instances, query API versions, DB engines, DB engine versions, and DB instance class supported by the system. The application scenarios are shown as follows.
.. figure:: /_static/images/en-us_image_0208249507.png
:alt: **Figure 1** Scenarios
**Figure 1** Scenarios
Before creating a DB instance, you need to obtain the DB engines and versions, DB instance class, and AZs supported by the system.
After obtaining the information, you can use the returned results as invoked parameters to create a DB instance.
After a DB instance is created, you can query the instance list and delete the instance.

410
api-ref/source/api_description/db_instance_management/creating_a_db_instance.rst Normal file
View File

File diff suppressed because it is too large Load Diff

73
api-ref/source/api_description/db_instance_management/deleting_a_db_instance.rst Normal file
View File

@ -0,0 +1,73 @@
:original_name: dds_api_0022.html
.. _dds_api_0022:
Deleting a DB Instance
======================
Function
--------
This API is used to delete a DB instance.
URI
---
- URI format
DELETE /v3/{project_id}/instances/{instance_id}
- Parameter description
.. table:: **Table 1** Parameter description
=========== ========= =================================================
Name Mandatory Description
=========== ========= =================================================
project_id Yes Specifies the project ID of a tenant in a region.
instance_id Yes Specifies the DB instance ID.
=========== ========= =================================================
Requests
--------
- Request header
.. code-block:: text
DELETE https://DDS endpoint/v3/{project_id}/instances/{instance_id}
- Request body
N/A
Responses
---------
- Parameter description
.. table:: **Table 2** Parameter description
====== ====== ==========================
Name Type Description
====== ====== ==========================
job_id String Indicates the workflow ID.
====== ====== ==========================
- Response example
.. code-block:: text
{
"job_id": "252f11f1-2912-4c06-be55-1999bde659c5"
}
**Status Code**
---------------
For more information, see :ref:`Status Code <dds_status_code>`.
Error Code
----------
For more information, see :ref:`Error Code <dds_error_code>`.

18
api-ref/source/api_description/db_instance_management/index.rst Normal file
View File

@ -0,0 +1,18 @@
:original_name: dds_instance_mgmt.html
.. _dds_instance_mgmt:
DB Instance Management
======================
- :ref:`Creating a DB Instance <dds_api_0020>`
- :ref:`Deleting a DB Instance <dds_api_0022>`
- :ref:`Querying DB Instances <dds_api_0023>`
.. toctree::
:maxdepth: 1
:hidden:
creating_a_db_instance
deleting_a_db_instance
querying_db_instances

512
api-ref/source/api_description/db_instance_management/querying_db_instances.rst Normal file
View File

File diff suppressed because it is too large Load Diff

20
api-ref/source/api_description/index.rst Normal file
View File

@ -0,0 +1,20 @@
:original_name: dds_api_description.html
.. _dds_api_description:
API Description
===============
- :ref:`Querying the API Version <dds_api_version>`
- :ref:`Querying Database Version Information <dds_database_version>`
- :ref:`Querying All DB Instance Specifications <dds_instance_specification>`
- :ref:`DB Instance Management <dds_instance_mgmt>`
.. toctree::
:maxdepth: 1
:hidden:
querying_the_api_version/index
querying_database_version_information
querying_all_db_instance_specifications
db_instance_management/index

318
api-ref/source/api_description/querying_all_db_instance_specifications.rst Normal file
View File

File diff suppressed because it is too large Load Diff

77
api-ref/source/api_description/querying_database_version_information.rst Normal file
View File

@ -0,0 +1,77 @@
:original_name: dds_database_version.html
.. _dds_database_version:
Querying Database Version Information
=====================================
Function
--------
This API is used to obtain database version information about a specified type of a DB instance.
URI
---
- URI format
GET /v3/{project_id}/datastores/{datastore_name}/versions
- Parameter description
.. table:: **Table 1** Parameter description
+----------------+-----------+--------------------------------------------------------------------------------------------------+
| Name | Mandatory | Description |
+================+===========+==================================================================================================+
| project_id | Yes | Specifies the project ID of a tenant in a region. |
+----------------+-----------+--------------------------------------------------------------------------------------------------+
| datastore_name | Yes | Specifies the database type. DDS Community Edition is supported. The value is **DDS-Community**. |
+----------------+-----------+--------------------------------------------------------------------------------------------------+
Requests
--------
- Request header
.. code-block:: text
GET https://DDS endpoint/v3/{project_id}/datastores/{datastore_name}/versions
- Request body
N/A
Responses
---------
- Parameter description
.. table:: **Table 2** Parameter description
+----------+------------------+--------------------------------------------------------------------------------+
| Name | Type | Description |
+==========+==================+================================================================================+
| versions | Array of strings | Indicates the database version. Currently, versions 3.2 and 3.4 are supported. |
+----------+------------------+--------------------------------------------------------------------------------+
- Response example
.. code-block:: text
{
"versions": [
"3.2",
"3.4"
]
}
**Status Code**
---------------
For more information, see :ref:`Status Code <dds_status_code>`.
Error Code
----------
For more information, see :ref:`Error Code <dds_error_code>`.

16
api-ref/source/api_description/querying_the_api_version/index.rst Normal file
View File

@ -0,0 +1,16 @@
:original_name: dds_api_version.html
.. _dds_api_version:
Querying the API Version
========================
- :ref:`Querying the API Version List <dds_api_0018>`
- :ref:`Querying API Version Information <dds_api_0019>`
.. toctree::
:maxdepth: 1
:hidden:
querying_the_api_version_list
querying_api_version_information

108
api-ref/source/api_description/querying_the_api_version/querying_api_version_information.rst Normal file
View File

File diff suppressed because it is too large Load Diff

114
api-ref/source/api_description/querying_the_api_version/querying_the_api_version_list.rst Normal file
View File

File diff suppressed because it is too large Load Diff

23
api-ref/source/api_overview.rst Normal file
View File

@ -0,0 +1,23 @@
:original_name: dds_api_0006.html
.. _dds_api_0006:
API Overview
============
DDS provides extension APIs, allowing you to perform specific operations using APIs.
.. table:: **Table 1** API description
+----------------------------------------+-------------------------------------------------------------------------------+
| Type | Description |
+========================================+===============================================================================+
| API Version Queries | - Query all API versions. |
| | - Query a specified API version. |
+----------------------------------------+-------------------------------------------------------------------------------+
| Database Version Information Queries | Obtain database version information about a specified instance type. |
+----------------------------------------+-------------------------------------------------------------------------------+
| All DB Instance Specifications Queries | Query all DB instance specifications in a specified region. |
+----------------------------------------+-------------------------------------------------------------------------------+
| DB Instance Management | Manage DB instances, including creating, deleting, and querying DB instances. |
+----------------------------------------+-------------------------------------------------------------------------------+

408
api-ref/source/appendix/dds_metrics.rst Normal file
View File

File diff suppressed because it is too large Load Diff

273
api-ref/source/appendix/error_code.rst Normal file
View File

File diff suppressed because it is too large Load Diff

20
api-ref/source/appendix/index.rst Normal file
View File

@ -0,0 +1,20 @@
:original_name: dds_public_parameters.html
.. _dds_public_parameters:
Appendix
========
- :ref:`Status Code <dds_status_code>`
- :ref:`Error Code <dds_error_code>`
- :ref:`Obtaining a Project ID <dds_projectid>`
- :ref:`DDS Metrics <dds_metrics>`
.. toctree::
:maxdepth: 1
:hidden:
status_code
error_code
obtaining_a_project_id
dds_metrics

66
api-ref/source/appendix/obtaining_a_project_id.rst Normal file
View File

@ -0,0 +1,66 @@
:original_name: dds_projectid.html
.. _dds_projectid:
Obtaining a Project ID
======================
Scenarios
---------
A project ID is required for some URLs when an API is called. Therefore, you need to obtain a project ID in advance. Two methods are available:
- :ref:`Obtaining the Project ID by Calling an API <dds_projectid__section18520151052413>`
- :ref:`Obtain a Project ID from the Console <dds_projectid__section127010198244>`
.. _dds_projectid__section18520151052413:
Obtaining the Project ID by Calling an API
------------------------------------------
The API used to obtain a project ID is **GET https://{Endpoint}/v3/projects**. **{Endpoint}** is the IAM endpoint and can be obtained from `Regions and Endpoints <https://docs.otc.t-systems.com/en-us/endpoint/index.html>`__ For details about API authentication, see :ref:`Token Authentication <dds_api_0010>`.
The following is an example response. The value of **id** is the project ID.
.. code-block::
{
"projects": [
{
"domain_id": "65382450e8f64ac0870cd180d14e684b",
"is_domain": false,
"parent_id": "65382450e8f64ac0870cd180d14e684b",
"name": "project_name",
"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"
}
}
.. _dds_projectid__section127010198244:
Obtain a Project ID from the Console
------------------------------------
#. Register yourself on the management console and log in to it.
#. Move your pointer over the username and select **My Credential** in the displayed drop-down list.
On the **My Credential** page, view the project ID in the project list.
.. figure:: /_static/images/en-us_image_0208249570.jpg
:alt: **Figure 1** Viewing project IDs
**Figure 1** Viewing project IDs

57
api-ref/source/appendix/status_code.rst Normal file
View File

@ -0,0 +1,57 @@
:original_name: dds_status_code.html
.. _dds_status_code:
Status Code
===========
- Normal
=========== ======== ============================================
Status Code Message Description
=========== ======== ============================================
200 OK Request succeeded.
202 Accepted Asynchronous request submitted successfully.
=========== ======== ============================================
- Abnormal
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Status Code | Message | Description |
+=======================+==========================+=================================================================================================================================================================================================================================================================+
| 400 | Bad Request | Invalid request. |
| | | |
| | | The client should not repeat the request without modifications. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 401 | Unauthorized | The authorization information provided by the client is incorrect or invalid. Check the username and password. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 403 | Forbidden | The request is rejected. |
| | | |
| | | The server has received and understood the request; yet it refused to respond, because the request is set to deny access. Do not retry the request before modification. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 404 | Not Found | The requested resource cannot be found. |
| | | |
| | | The client should not repeat the request without modifications. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 405 | Method Not Allowed | The method specified in the request is not supported for the requested resource. |
| | | |
| | | The client should not repeat the request without modifications. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 409 | Conflict | The request could not be processed due to a conflict. |
| | | |
| | | This status code indicates that the resource that the client attempts to create already exits, or the request fails to be processed because of the update of the conflict request. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 413 | Request Entity Too Large | The request is larger than that a server is able to process. The server may close the connection to prevent the client from continuing the request. If the server temporarily cannot process the request, the response will contain a Retry-After header field. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 415 | Unsupported Media Type | The server is unable to process the media format in the request. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 422 | Unprocessable Entity | The request is well-formed but is unable to be processed due to semantic errors. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 500 | Internal Server Error | The server is able to receive the request but it could not understand the request. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 501 | Not Implemented | The server does not support the requested function. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 503 | Service Unavailable | The requested service is invalid. |
| | | |
| | | The client should not repeat the request without modifications. |
+-----------------------+--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

26
api-ref/source/before_you_start.rst Normal file
View File

@ -0,0 +1,26 @@
:original_name: dds_api_reference.html
.. _dds_api_reference:
Before You Start
================
This document describes application programming interfaces (APIs), syntax, parameters, and examples of Document Database Service (DDS). You can search for information you need according to :ref:`Table 1 <dds_api_reference__table333417544226>`.
.. _dds_api_reference__table333417544226:
.. table:: **Table 1** Documentation guide
+------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| Section | Description |
+================================================+========================================================================================================================================================+
| :ref:`API Overview <dds_api_0006>` | DDS API components and API list |
+------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Environment Preparations <dds_api_0007>` | Preparations before using the APIs, including obtaining the request authentication and project ID |
+------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`API Calling <dds_api_0014>` | Representational State Transfer (REST) message bodies, calling methods, and examples |
+------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`API Description <dds_api_description>` | DDS APIs, including APIs used for querying information about API version, database version, and DB instance specifications, and managing DB instances. |
+------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Appendix <dds_public_parameters>` | Understand the status codes and error codes about DDS APIs. |
+------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+

26
api-ref/source/change_history.rst Normal file
View File

@ -0,0 +1,26 @@
:original_name: dds_change_history.html
.. _dds_change_history:
Change History
==============
+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Date | Description |
+===================================+=========================================================================================================================================================================================================================================================================================+
| 2020-10-15 | Modified the following content: |
| | |
| | - Modified the description of the **ram** parameter in :ref:`Querying All DB Instance Specifications <dds_instance_specification>`. |
| | - Modified the description of the **disk_encryption_id** parameter in :ref:`Querying DB Instances <dds_api_0023>`. |
+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 2019-11-07 | Modified the following content: |
| | |
| | - Modified the value of **versions** in the response example in :ref:`Querying Database Version Information <dds_database_version>`. |
| | - Modified the description of the **num** parameter in :ref:`Creating a DB Instance <dds_api_0020>`. |
+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 2019-09-25 | Modified the following content: |
| | |
| | - Change the value of **spec_code** in the request and response examples in :ref:`Example <dds_api_0017>`, :ref:`Querying All DB Instance Specifications <dds_instance_specification>`, :ref:`Creating a DB Instance <dds_api_0020>`, and :ref:`Querying DB Instances <dds_api_0023>`. |
+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 2019-08-19 | This issue is the first official release. |
+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

14
api-ref/source/environment_preparations/index.rst Normal file
View File

@ -0,0 +1,14 @@
:original_name: dds_api_0007.html
.. _dds_api_0007:
Environment Preparations
========================
- :ref:`Token Authentication <dds_api_0010>`
.. toctree::
:maxdepth: 1
:hidden:
token_authentication

83
api-ref/source/environment_preparations/token_authentication.rst Normal file
View File

@ -0,0 +1,83 @@
:original_name: dds_api_0010.html
.. _dds_api_0010:
Token Authentication
====================
Application Scenarios
---------------------
If you use a token for authentication, you must obtain the user's token and add **X-Auth-Token** to the request message header of the service API when making an API call.
This section describes how to make an API call for token authentication.
Invoking an API
---------------
#. .. _dds_api_0010__en-us_topic_0110967262_li14280177102918:
Obtain the following information:
a. To obtain the IAM endpoint and region name in the message body, see `Regions and Endpoints <https://docs.otc.t-systems.com/en-us/endpoint/index.html>`__.
b. To obtain the project ID, see :ref:`Obtaining a Project ID <dds_projectid>`.
#. .. _dds_api_0010__en-us_topic_0110967262_li109381224173013:
Send a POST https://*IAM\_Endpoint*/v3/auth/tokens request to obtain the user token.
.. table:: **Table 1** Header description
+--------------+----------------------------------------------+-----------+------------------+
| Name | Description | Mandatory | Example |
+==============+==============================================+===========+==================+
| Content-Type | Specifies the MIME type of the request body. | Yes | application/json |
+--------------+----------------------------------------------+-----------+------------------+
An example request message is as follows:
.. code-block:: text
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"name": "username",
"password": "password",
"domain": {
"name": "domainname"
}
}
}
},
"scope": {
"project": {
"id": "project_id"
}
}
}
}
In the preceding command, replace parameter in italic with the actual values. For details, see the "Obtaining a User Token" section in the *Identity and Access Management API Reference*.
a. **IAM\_Endpoint**: Replace it with the IAM endpoint obtained in :ref:`1 <dds_api_0010__en-us_topic_0110967262_li14280177102918>`.
b. **username** and **password**: Replace them respectively with the username and password of the IAM server.
c. **project_id**: Replace it with the project ID obtained in :ref:`1 <dds_api_0010__en-us_topic_0110967262_li14280177102918>`.
After the request is processed, the value of **X-Subject-Token** in the header is the token value.
.. code-block::
X-Subject-Token:MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...
#. Run the following command to set the token as an environment variable for subsequent operations:
**export Token=\ {**\ *X-Subject-Token*\ **}**
**X-Subject-Token**: Replace it with the token obtained in :ref:`2 <dds_api_0010__en-us_topic_0110967262_li109381224173013>`. An example command is as follows:
**export Token=MIIDkgYJKoZIhvcNAQcCoIIDgzCCA38CAQExDTALBglghkgBZQMEAgEwgXXXXX...**

10
api-ref/source/index.rst
View File

@ -2,3 +2,13 @@
Document Database Service - API Reference Document Database Service - API Reference
========================================= =========================================
.. toctree::
:maxdepth: 1
before_you_start
api_overview
environment_preparations/index
api_calling/index
api_description/index
appendix/index
change_history