---
title: API JSON files configuration
description: Learn what application programming interface (API) JavaScript Object Notation (JSON) files are and how they are configured to secure the APIs in your environment.
component: pingintelligence
version: 5.2
page_id: pingintelligence:pingintelligence_reference_guide:pingintelligence_configure_api_json
canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/pingintelligence_reference_guide/pingintelligence_configure_api_json.html
revdate: April 3, 2024
section_ids:
  adding-api-json-files: Adding API JSON files
  about-this-task: About this task
  steps: Steps
  choose-from: Choose from:
  listing-api-json-files: Listing API JSON files
  steps-2: Steps
  example: Example:
  updating-api-json-files: Updating API JSON files
  about-this-task-2: About this task
  steps-3: Steps
  choose-from-2: Choose from:
---

# API JSON files configuration

Learn what application programming interface (API) *(tooltip: \<div class="paragraph">
\<p>A specification of interactions available for building software to access an application or service.\</p>
\</div>)* JavaScript Object Notation (JSON) *(tooltip: \<div class="paragraph">
\<p>An open, lightweight data-interchange format that uses human-readable text to store and transmit data.\</p>
\</div>)* files are and how they are configured to secure the APIs in your environment.

API JSON files are used to configure the behavior and properties of your APIs in API Security Enforcer (ASE). The parameters in API JSON files help ASE to uniquely identify the APIs in your environment. Each API has a unique API JSON file in ASE. ASE ships with sample JSON files located in the `/config/api` directory.

The parameters configured in an API JSON file help ASE extract metadata from API traffic, set decoys to trap intruding attacks, perform health checks on backend servers, and so on. The API JSON parameters also help the API Behavioral Security (ABS) AI Engine to build AI models to detect any indicators of attacks (IoAs) on APIs.

See the following for more information on the parameters in API JSON files:

* [Defining an API using API JSON configuration file in sideband mode](pingintelligence_define_api_json_file_sideband.html)

* [Defining an API using API JSON configuration file in inline mode](pingintelligence_defining_api_json_configuration_inline.html)

![Image showing API JSON files secured by ASE connected to backend servers](../_images/pqn1628167906884.png)

You can manually configure the JSON file with the required parameters and add them to ASE.

|   |                                                                                                                                     |
| - | ----------------------------------------------------------------------------------------------------------------------------------- |
|   | The sample JSON file has an extension of `.example`. If you are customizing the example file, then save the file as a `.json` file. |

## Adding API JSON files

### About this task

After configuring an API JSON file, add it to ASE to activate ASE processing.

### Steps

* To add an API, do one of the following:

  #### Choose from:

  * Run the following command-line interface (CLI) command:

    ```
    /<ASE_Installation path>/pingidentity/ase/bin/cli.sh –u admin -p admin add_api {file_path/api_name}
    ```

  * Use the [Create API](pingintelligence_rest_api_inline_sideband_ase.html) in ASE Admin APIs to add an API JSON file to ASE.

    The following is a sample `curl` command for it:

    ```shell
    curl --location --request POST '{{API}}=<API Name>' \
    --header '{{Access_Key_Header}}: {{Access_Key}}' \
    --header '{{Secret_Key_Header}}: {{Secret_key}}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "api_metadata": {
            "protocol": "https",
            "url": "/patmapp",
            "hostname": "*",
            "oauth2_access_token": false,
            "apikey_qs": "",
           <<Request body continues...>>
    ```

## Listing API JSON files

### Steps

* Check the addition of an API JSON file to ASE by running the following CLI command:

  ```
  /<ASE_Installation path>/pingidentity/ase/bin/cli.sh –u admin -p admin list_api
  ```

* Use [List API](pingintelligence_rest_api_inline_sideband_ase.html) in ASE Admin APIs to verify.

  #### Example:

  The following is a sample `curl` command for it:

  ```shell
  curl --location --request GET '{{List_API}}' \
  --header '{{Access_Key_Header}}: {{Access_Key}}' \
  --header '{{Secret_Key_Header}}: {{Secret_key}}'
  ```

## Updating API JSON files

### About this task

After activation, an API JSON definition can be updated in real time.

### Steps

* To update the API JSON file:

  #### Choose from:

\*\*

1. Edit the API JSON file located in the `/config/api` directory and make the desired changes.

2. Save the edited API JSON file and run the following CLI command:

   ```
   /<ASE_Installation path>/pingidentity/ase/bin/cli.sh –u admin -p admin update_api  <api_name>
   ```

   The following is an example:

   ```
   /opt/pingidentity/ase/bin/cli.sh –u admin -p admin update_api shop
   api shop updated successfully
   ```

   * You can also use [Update API](pingintelligence_rest_api_inline_sideband_ase.html) in ASE Admin APIs to update the JSON.

   The following is a sample `curl` command for it:

   \+

   ```shell
   curl --location --request PUT '{{API}}=<API Name>' \
   --header '{{Access_Key_Header}}: {{Access_Key}}' \
   --header '{{Secret_Key_Header}}: {{Secret_key}}' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "api_metadata": {
           "protocol": "https",
           "url": "/pubatmapp",
           "hostname": "*",
           "oauth2_access_token": false,
           <<Request body continues...>>
   ```