# API Registry

<mark style="color:green;">**Path: API Management > API Registry**</mark>

The system can register the APIs saved on the AP server to the system, and have the system manage the APIs.

The system provides two methods to allow users to register APIs, which are through API documents and http / https to register the APIs to the system.

### OPENAPI(OpenAPI) <a href="#toc169186085" id="toc169186085"></a>

In this section, you can find instructions on how to register APIs to the system using documents compliant with OAS 2.0 or OAS 3.0, including batch registration.

{% hint style="warning" %}
API documents must conform to OAS2.0 or OAS3.0 format to use this feature.
{% endhint %}

<figure><img src="/files/9y2VEonMlRK4yrrHIkCZ" alt=""><figcaption></figcaption></figure>

1. To upload an OpenAPI document via URL, select **Upload OpenAPI document via URL,** paste the DOC URL into the field, and click **Upload** to proceed.

<figure><img src="/files/Draa8emDwQEEVen6OgEB" alt=""><figcaption></figcaption></figure>

2. The information of this API will be displayed below.

{% hint style="info" %}
The example is <https://petstore3.swagger.io/api/v3/openapi.json>.
{% endhint %}

<figure><img src="/files/UsZ8RUjTKp5uD0hVlIfv" alt=""><figcaption></figcaption></figure>

3. Fill in the API related fields.
   * **Target URL**<mark style="color:red;">**\***</mark>**:** Only for registered API, if the source URL has been changed, the new URL can be specified here.
4. For the underlying API, click on the ![](/files/GL9Nedl2hkUQCDePrXdW) icon to access the test external URL page, then click **Validate** to test whether this API can be used normally.

<figure><img src="/files/qZqNE0ZYM19IPYTjGRFU" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/X4pQpr4ExRvuqoYK2B4q" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/yIiLwGYyL9WCwOTsbPzU" alt=""><figcaption></figcaption></figure>

5. Click on the ![](/files/8NCFE7I8LK3txf55vObV) icon of the underlying API to expand the information of this API, and click on the ![](/files/8LApCloRTZPU4g6DTu1y) icon to collapse.

<figure><img src="/files/9sysMvy3qh2idZZFnx8L" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/zrE7QJKw5vi0lm5miWRC" alt=""><figcaption></figcaption></figure>

6. After clicking **Register**, all APIs in this API module will be registered to the system.
7. Since the registered APIs are all disabled by default, they must be enabled manually from **API Management** > **API List**.

### CUSTOMIZE <a href="#hlk168306724" id="hlk168306724"></a>

In this section, you can find instructions on how to mount external APIs onto the system using URL methods; the default mode is **New(dgrc)**.

<figure><img src="/files/nHYa2lKaoVMvvfhiGVi5" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/JV0FPbHesB7KVngk9VTt" alt=""><figcaption></figcaption></figure>

1. Fill in the data or make selections as instructed below. The fields marked with “<mark style="color:$danger;">\*</mark>” are required.

* **Clone from existing API**: Clone an existing API to create a new one. Enter the API ID or select it from the API list, then click **copy**.

* **Modes**: Two API modes are available, **Default Mode(dgrc)** and **dgRv3 compatible(tsmpc)**.
  * **Default Mode(dgrc)**:
    * Fill in **API Name**<mark style="color:$danger;">**\***</mark>, and configure the URL path if needed.
    * The system backend options include **HTTP API**, **AI Gateway**, and **Webhook**. The default is **HTTP API**.
  * **dgRv3 compatible(tsmpc)**: Fill in both **API Module**\* and **API ID**\*.

* **Target URL**<mark style="color:$danger;">**\***</mark>: URL of the API.

  * Click on the ![](/files/3bfvsH0g3r1iCLe31BiW) / ![](/files/jKMPcAnEcQvhrOBoFoSG) icon to add/remove URLs.
  * **mtls**: Check to enable mutual TLS authentication. Available only in **Default Mode(dgrc)**.
  * If the backend is set to **HTTP API**:

    * Copy the API URL to upload, and paste it to the **Target URL**<mark style="color:$danger;">**\***</mark> field.

    <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The example is from <em>Google API Explorer</em>: <a href="https://developers.google.com/apis-explorer/">https://developers.google.com/apis-explorer/</a>.</p></div>

    * Source IP Diversion: Check to distribute traffic based on the source IP address, allowing for more efficient management of network traffic.
    * Click Validate to test the configured URL and display the result

    <figure><img src="/files/rHWKyelIxOiyWegCFO9l" alt=""><figcaption></figcaption></figure>

    <figure><img src="/files/nr27wiPO8t2eJ2Y7idWB" alt=""><figcaption></figcaption></figure>

    * **Source IP Diversion**: Check to distribute traffic based on the source IP address, allowing for more efficient management of network traffic.
    * Click Validate to test the configured URL and display the result.

      * To check if the **Http Methods**<mark style="color:$danger;">**\***</mark> and **Target URL**<mark style="color:$danger;">\*</mark> fields are correct, Click **Validate**.

      <figure><img src="/files/lQ2schiW862Dkmi4npQi" alt=""><figcaption></figcaption></figure>
    * The result will be displayed below. If the result is Status *200* and there were data in Headers and Body, it means that this API can be used.
    *

    ```
    <figure><img src="/files/7T7kkEixv0GmIFQ3T1FX" alt=""><figcaption></figcaption></figure>
    ```

    * If the backend is set to **AI Gateway**:
      * Click **AI APIKEY** to have the system automatically populate the URL.
      * **AI APIKEY**: Go to **AI Gateway** > **AI APIKEY** to complete the required setup before use.
    * If the backend is set to **Webhook**:
      * The system will automatically populate the URL. Click **Validate** to test the configured URL and display the result.
      * **Webhook Notify Name:** Select the Webhook to register. Go to **System Configs > Webhook** to complete the Webhook setup before use.

* **API Log Header Mask**: Specify masking for the **Header** field. For example, if the value is Hello, with a character count of *1* and masking character #, the following will be displayed:
  * Policy 0: No masking, displays Hello.
  * Policy 1: Retains the first and last character, displays H###o.
  * Policy 2: Retains the first character, displays H####.
  * Policy 3: Retains the last character, displays ####o.

* **API Log Body Mask Policy**: Specify different masking for keywords in the **Body** content, with support for regular expressions. For example, if the original text, "name":"test","id":"1", with a character count of *2*, masking character #, and keyword name, the following will be displayed:

  * Policy 0: No masking, displays "name":"test","id":"1".
  * Policy 1: Masks the first and last 2 characters, displays "#name##"test","id":"1".
  * Policy 2: Masks the first 2 characters, displays "#name":"test","id":"1".
  * Policy 3: Masks the last 2 characters, displays "#name##"test","id":"1".

  Policy 4 uses regular expressions for definition. For example, with a character count of *1* and a mask of #, and a regular expression of name\d, the following will be displayed:

  * "name1":"test","id":"1" will display as "name1#:"test","id":"1".
  * "name2":"test","id":"1" will display as "name2#:"test","id":"1".
  * "name-3":"test","id":"1" will display as "name-3:"test","id":"1".

* **Fail Discovery Policy**<mark style="color:$danger;">\*</mark>: Specify the action to take when an API connection fails. The system default is set to **When the connection fails or the HTTP status code is 4xx (client error) or 5xx (server error)**; available only in **Default Mode(dgrc)**.

* **Fail Handle Policy**<mark style="color:$danger;">\*</mark>: Specify how the system handles API connection failures. Choose between No retries or **When calling the target URL fails, automatically retry the next target URL**; available only in **Default Mode(dgrc)**.

* **API Module**<mark style="color:$danger;">\*</mark>: New module name of the API in **dgRv3 compatible(tsmpc)** mode, used for external URL calls. Only alphanumeric characters, underscore “\_” and hyphen “-” are allowed in this field.

* **API ID**<mark style="color:$danger;">\*</mark>: API identification name in **dgRv3 compatible(tsmpc)** mode, used for external URL calls. Only alphanumeric characters, underscore “\_” and hyphen “-” are allowed in this field.

* **API Name**<mark style="color:$danger;">\*</mark>: API name in **Default Mode(dgrc)**, used for external URL calls.

* **digiRunner URL**: In **dgRv3 compatible(tsmpc)** mode, the system automatically generates the API call URL for external systems using the specified **Module Name**<mark style="color:$danger;">\*</mark> and **API ID**<mark style="color:$danger;">\*</mark> . Check to set the authentication method to **Path Parameter** or **No Auth**:
  * **Path Parameter**: Upon checking, carries over the URL path parameter data when calling the API.
  * **No Auth**: Upon checking, allows calling the API without authentication, commonly used for Public APIs.

* **digiRunner Proxy Path**<mark style="color:$danger;">\*</mark>: Required only when **Default Mode(dgrc)** is selected. This field maps to the path of the **Target URL**<mark style="color:$danger;">\*</mark>. The first character must be "/", and any parameters in the path should be represented as {p}.
  * For example:

    * If the target URL is a.b.c/a1/a2, the Proxy Path is /x1/x2.
    * If the target URL is a.b.c/a1/{id}, the Proxy Path is /x1/x2/{p}.
    * If the target URL is a.b.c/a1/{id1}/a3/{id2}, the Proxy Path is /x1/{p}/x2/{p}.
    * No Auth: Upon checking, allows calling the API without authentication, commonly used for Public APIs.

    <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>If <strong>Default</strong> <strong>Mode(dgrc)</strong> is checked, the registered digiRunner Proxy Path does not need to include /tsmpc (this is the context path used for compatibility mode in the old version).</p></div>

* **Http Methods**<mark style="color:$danger;">\*</mark>: Specify the HTTP methods of this API, including GET, POST, PUT, DELETE, etc.

* **Data Format**: Select the data format for the upload; it is JSON by default.

* **JWT Settings**: Set whether to use JWE or JWS encryption for Request / Response.

* **Description**: API description.

* **Label**: Fill in the desired text and click the **ENTER** key to create the label, with a limit of up to five labels allowed. Labels with capitalized characters will automatically be converted to lowercase, and each label can be no more than 20 characters long.

2. Since the registered APIs are all disabled by default, they must be enabled manually from **API Management > API List**. Add the API to the group again in order for users to use it.
3. To test this API, go to **API Management > API List** to search and test whether this API can be used by users.

{% hint style="info" %}
Ensure the API is added to a group assigned to the user so the user can access it.
{% endhint %}

4. Multiple external APIs can also be added. If multiple APIs were added, the system will open APIs randomly when testing in the test area.

<figure><img src="/files/vLOO4LkjBdK1OHihcJLz" alt=""><figcaption></figcaption></figure>

5. You can copy an existing API on the system. Click on the ![](/files/2pZdvetFHatV2To4UKmq) icon.

<div align="left"><figure><img src="/files/0YxX2mI6pOOCy8RTaHCT" alt=""><figcaption></figcaption></figure></div>

&#x20;

6. Go to **Clone from existing API**, search for and check the desired API, and click **Join**.

<figure><img src="/files/DQTtx6vwFNYv1iBVoV17" alt=""><figcaption></figcaption></figure>

7. Click **copy** to copy and change to a new API.

{% hint style="danger" %}
NOTE: If the API basic information remains unchanged, a warning prompt will pop up, displaying the error message “1353 - \[API] already exists”.
{% endhint %}

<div align="left"><figure><img src="/files/WyUH0jHw4dwQT4pc9nQw" alt=""><figcaption></figcaption></figure></div>

<figure><img src="/files/q135ujjjbYFtg2GhRYaY" alt=""><figcaption></figcaption></figure>

<div align="left"><figure><img src="/files/3EoXSpdwjf20Vc3euyY4" alt=""><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tpi.dev/guide/api-management/api-registry.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.