--- title: Defining an API using API JSON configuration file in inline mode description: The application programming interface (API) JavaScript Object Notation (JSON) file parameters define the behavior and properties of your API. component: pingintelligence version: 5.2 page_id: pingintelligence:pingintelligence_reference_guide:pingintelligence_defining_api_json_configuration_inline canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/pingintelligence_reference_guide/pingintelligence_defining_api_json_configuration_inline.html revdate: June 7, 2024 section_ids: example: Example adding-a-configured-api-json-file-to-ase: Adding a configured API JSON file to ASE before-you-begin: Before you begin about-this-task: About this task steps: Steps updating-a-configured-api: Updating a configured API about-this-task-2: About this task steps-2: Steps result: Result: --- # Defining an API using API JSON configuration file in inline mode The application programming interface (API) *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)* JavaScript Object Notation (JSON) *(tooltip: \
\

An open, lightweight data-interchange format that uses human-readable text to store and transmit data.\

\
)* file parameters define the behavior and properties of your API. The sample API JSON files shipped with API Security Enforcer (ASE) can be changed to your environment settings and are populated with default values. The following table describes the JSON file parameters. | Parameter | Description | | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `protocol` | API request type with supported values of:- `ws` - WebSocket - `http` - HTTP | | `url` | The value of the URL for the managed API. You can configure up to six levels of sub-paths. For example:- `/shopping` - name of a 1 level API - `/shopping/electronics/phones/brand` - 4 level API - `/` - entire server. Used for API Behavioral Security (ABS) API Discovery or load balancing. | | `hostname` | Host name for the API. The value cannot be empty.`"*"` matches any host name. | | `cookie` | Name of cookie used by the backend servers. | | `cookie_idle_timeout` | The amount of time a cookie is valid, such as 20m for 20 minutes.The time duration formats include:- s - seconds - m - minutes - h - hour - d - day - w - week - mnt - month - yr - year | | `logout_api_enabled` | When `true`, ASE expires cookies when a logout request is sent. | | `cookie_persistence_enabled` | When `true,` the subsequent request from a client is sent to the server which initially responded. | | `oauth2_access_token` | When `true`, ASE captures OAuth2 Access Tokens.When `false`, ASE does not look for OAuth2 Tokens. Default value is `false`.For more information, see [Capture client identifiers in inline mode](pingintelligence_capture_client_identifiers_inline.html). | | `is_token_mandatory` | When set to `true`, if the request has a missing token, ASE adds the IP address of the client to deny list and blocks the request. When set to `false`, ASE does not block the client. For ASE to check and block the client the following values must be set to true: oauth2\_access\_token enable\_firewall and enable\_ase\_detected\_attack in Inline ASE configuration using the ase.conf file.The default value is `false`. | | `apikey_qs` | When API Key is sent in the query string, ASE uses the specified `parameter name` to capture the API key value.For more information, see [Capture client identifiers in inline mode](pingintelligence_capture_client_identifiers_inline.html). | | `apikey_header` | When API Key is part of the header field, ASE uses the specified parameter name to capture the API key value.For more information, see [Capture client identifiers in inline mode](pingintelligence_capture_client_identifiers_inline.html). | | `login_url` | Public URL used by a client to connect to the application. | | `enable_blocking` | When `true`, ASE blocks all types of attack on this API. When `false,` no attacks are blocked.Default value is `false`. | | `api_memory_size` | Maximum ASE memory allocation for an API.The default value is 128 MB. The data unit can be MB or GB. | | `health_check` | When `true,` enable health checking of backend servers.When `false`, no health checks are performed.Ping Identity recommends setting this parameter as `true`. | | `health_check_interval` | The interval in seconds at which ASE sends a health check to determine backend server status. | | `health_retry_count` | The number of times ASE queries the backend server status after not receiving a response. | | `health_url` | The URL used by ASE to check backend server status. | | `health_check_headers` | Configure one or more health check headers in the API JSON in a key-value format. This is an optional configuration and applies only to inline ASE deployment. In the sample JSON, the following example is provided:``` "health_check_headers": { "X-Host": "%{HOST}", "X-Custom-Header": "value" }, ```The next table explains the sample JSON. | | `server_ssl` | When set to `true`, ASE connects to the backend API server over Secure Sockets Layer (SSL) *(tooltip: \
\

A protocol for authenticated and encrypted links between networked machines, typically over HTTPS. SSL was deprecated in 1999 in favor of Transport Layer Security (TLS).\

\
)*. If set to `false`, ASE uses TCP to connect to the backend server. | | Servers:`host` `port` `server_spike_threshold` `server_connection_quota` | The IP address or hostname and port number of each backend server running the API.See [REST API Protection from DoS and DDoS](pingintelligence_ase_dos_ddos_protection.html) for information on optional flow control parameters. | | **API Mapping:**`internal_url` | Internal URL is mapped to the public external URLSee [API Name Mapping – Protect Internal URLs](pingintelligence_api_name_mapping_hide_internal_urls.html) for more information | | The following API Pattern Enforcement parameters only apply when API Firewall is activated | | | **Flow Control**`client_spike_threshold``server_connection_queueing``bytes_in_threshold``bytes_out_threshold` | ASE flow control ensures that backend API servers are protected from surges (for example DDoS, traffic spike) in API traffic.See [WebSocket API Protection from DoS and DDoS](pingintelligence_websocket_api_protection_dos_ddos.html) for information on parameters. | | `protocol_allowed` | List of accepted protocolsValues can be HTTP, HTTPS, WS, WSS. When Firewall is enabled, protocol\_allowed takes precedence over the protocol parameter. | | `http_redirect``response_code``response_def``https_url` | Redirect unencrypted HTTP requests to `http_redirect`, the FQDN address of a HTTPS secure connection.See [Configuring Pattern Enforcement](pingintelligence_ase_attack_detection.html) for details. | | `methods_allowed` | List of accepted REST API methods. Possible values are:- `GET` - `POST` - `PUT` - `DELETE` - `HEAD` | | `content_type_allowed` | List of content types allowed. Multiple values cannot be listed. For example, application/json. | | `error_code``error_type``error_message_body` | Error message generated by ASE after blocking a client.See [ASE Detected Error Messages](pingintelligence_ase_error_messages_blocked_requests.html) for details. | | Decoy Config`decoy_enabled` `response_code` `response_def response_message` `decoy_subpaths` | When `decoy_enabled` is set to `true`, decoy sub-paths function as decoy APIs.response\_codeThe status code (for example, 200) that ASE returns when a decoy API path is accessed.response\_defThe response definition (for example OK) that ASE returns when a decoy API path is accessed.response\_messageThe response message (for example OK) that ASE returns when a decoy API path is accessed.decoy\_subpathsThe list of decoy API sub-paths (for example `shop/admin`, `shop/root)`.For more information see [Configuring API deception](pingintelligence_api_deception_environment_inline.html) for details. | | `username_header` | The name of the custom header containing username. When the value of `username_header` is set, ASE extracts the username from the custom header. For more information, see [Extract username from custom header in inline mode](pingintelligence_extract_username_header_inline_mode.html). You can configure username capture from either username\_header or JWT object, but not both. | | JWT`location` `username` `clientid` | When the parameter values of `JWT` object are set, ASE decodes the JWT to extract the user information.locationThe place of occurrence of JWT in an API request. The supported values are:- `qs:` - `h:` - `h:authorization:bearer` - `h:authorization:mac` - `h:cookie:`usernameThe JWT claim to extract the username.clientidThe JWT claim to extract the client-idFor more information, see [Extract user information from JWT in inline mode](pingintelligence_extract_user_info_jwt_inline.html). You can configure username capture from either JWT object or username\_header, but not both. | | Example Key | Value | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | X-Host | `%{HOST}` - If your backend server requires the value of header to contain host name or IP address of the server, use `%{HOST}` in value. During health check, ASE dynamically replaces header values containing %{HOST} with host name or IP address of the server.In the sample API JSON, ASE will dynamically replace %{HOST} with IP address (127.0.0.1) configured in the `servers` section.``` "servers": [ { "host": "127.0.0.1", "port": 8080, "server_spike_threshold": "0/second", "server_connection_quota": 0 } ], ``` | | X-Custom-Header | Your custom header value. All the custom health check headers configured are sent to all the backend API servers. | ## Example The following is a sample JSON file for a REST API: ```json { "api_metadata": { "protocol": "http", "url": "/rest", "hostname": "*", "cookie": "", "cookie_idle_timeout": "200m", "logout_api_enabled": false, "cookie_persistence_enabled": false, "oauth2_access_token": false, "is_token_mandatory": false, "apikey_qs": "", "apikey_header": "", "login_url": "", "enable_blocking": true, "api_mapping": { "internal_url": "" }, "api_pattern_enforcement": { "protocol_allowed": "", "http_redirect": { "response_code": "", "response_def": "", "https_url": "" }, "methods_allowed": [], "content_type_allowed": "", "error_code": "401", "error_def": "Unauthorized", "error_message_body": "401 Unauthorized" }, "flow_control": { "client_spike_threshold": "0/second", "server_connection_queueing": false }, "api_memory_size": "128mb", "health_check": false, "health_check_interval": 60, "health_retry_count": 4, "health_url": "/health", "health_check_headers": {}, "server_ssl": false, "servers": [ { "host": "127.0.0.1", "port": 8080, "server_spike_threshold": "0/second", "server_connection_quota": 0 }, { "host": "127.0.0.1", "port": 8081, "server_spike_threshold": "0/second", "server_connection_quota": 0 } ], "decoy_config": { "decoy_enabled": false, "response_code": 200, "response_def": "", "response_message": "", "decoy_subpaths": [] }, "username_header": "x-username-header", "jwt": { "location": "h:authorization:bearer", "username": "username", "clientid": "client_id" } } } ``` * Adding configured API * Updating configured API ## Adding a configured API JSON file to ASE ### Before you begin Configure an API JSON file. For more information, see [API JSON files configuration](pingintelligence_configure_api_json.html). ### About this task To add an API JSON file to ASE to activate ASE processing: ### Steps 1. To add an API, run the following command-line interface (CLI) command: ``` /opt/pingidentity/ase/bin/cli.sh –u admin -p admin add_api {file_path/api_name} ``` 2. Repeat step 2 for each API you want to add. ## Updating a configured API ### About this task After activation, to update an API JSON definition in real time: ### Steps 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: ``` /opt/pingidentity/ase/bin/cli.sh –u admin -p admin update_api ``` #### Result: ``` /opt/pingidentity/ase/bin/cli.sh –u admin -p admin update_api shop api shop updated successfully ```