# Track API Discovery Learning

When [a new Web API asset is added](https://waf-doc.inext.checkpoint.com/getting-started/protect-a-web-api) and API Discovery is activated, the underlying Machine Learning engine starts to gradually build a suggested schema of the web server's accepted APIs, as explained here:

{% content-ref url="api-discovery" %}
[api-discovery](https://waf-doc.inext.checkpoint.com/additional-security-engines/api-protection/api-discovery)
{% endcontent-ref %}

API Discovery also generates visibiity of your API usage in a dashboard that shows data for all your defined assets that use API Discovery, as explained here:

{% content-ref url="../../getting-started/monitor-events" %}
[monitor-events](https://waf-doc.inext.checkpoint.com/getting-started/monitor-events)
{% endcontent-ref %}

As time passes, and depending on the size of traffic, variance of request sources, the learning level will gradually increase. When a certain maturity level is reached (Master and above, after a minimum of 10 days), it is recommended to perform a final review of the suggested schema, and use it in the [Schema Validation enforcement](https://waf-doc.inext.checkpoint.com/additional-security-engines/api-protection/enforce-api-schema) configuration.

Following a certain maturity level, the learning engine will constantly continue to look at the traffic and discover potential suggested changes to the schema. However, at this stage changes will not be suggested until sufficient time has passed (several days, depending on the learn level it has reached) to make sure the changes detected are indeed consistent and required.

At times, the learning engine will request answers to questions about API where fine tuning is needed. Answering those questions improves the accuracy of the suggested schema.

## Understand The Learning Level

When HTTP requests are inspected API Discovery learning agent will reach different learning levels. Each level represents the maturity of the learning model and helps to understand what it needs to reach the next level. It will also indicate when it is time to use the suggested schema and activate [Schema Validation enforcement](https://waf-doc.inext.checkpoint.com/additional-security-engines/api-protection/enforce-api-schema). The model progresses through the following learning levels:

<figure><img src="https://2760087783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEWA4nfgNrSRL8dA6Kap7%2Fuploads%2FFaOKPwvQzSSB40hSymLF%2Fappsec-track-learning-learning-levels.png?alt=media&#x26;token=baaccf0c-6497-4d0e-bbcc-1127bc7fcc7c" alt=""><figcaption></figcaption></figure>

When the learning level becomes **Master,** it is recommended to use the suggested schema, after answering all fine tuning questions to achieve the highest accuracy of the suggested schema, review it, and enforce [Schema Validation](https://waf-doc.inext.checkpoint.com/additional-security-engines/api-protection/enforce-api-schema) using it.

#### Step 1: Track the learning level

<figure><img src="https://2760087783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEWA4nfgNrSRL8dA6Kap7%2Fuploads%2FvY4l1WX8G9QwaLQvpkd6%2FAPIDiscoveryLearn.png?alt=media&#x26;token=d2ade115-d561-4042-91fb-a23c11300796" alt=""><figcaption></figcaption></figure>

* Go to **Policy->Assets** and select the Asset you want to track.
* Select the **Learn** tab. This tab shows the learning **statistics of the last 7 days**, the **Elapsed Time**, the **Learning Level** and the **Recommendation** at this level.
* Below the summary you will find the detected schema and below that, the suggestions to the user that will help fine-tune the learning data (Tuning Suggestions).
* Hover over the **Learning Level** tooltip:information\_source: to learn the current learning level and the next level. It will also indicate what is required to reach the next level in the '**Watch next?'** section. Positive contributing factors to the learning process are: Time elapsed, amount of traffic inspected, amount of supervised learning suggestions and some other model parameters.&#x20;

#### Step 2: Address the recommended action

1. Hover over the **Recommendation** tooltip:information\_source: to learn what the current recommended action is for the asset. Recommendations include:

<table><thead><tr><th width="320">Recommendation</th><th>Action Required</th></tr></thead><tbody><tr><td>Send Traffic</td><td>Verify agent installation</td></tr><tr><td>Keep Learning</td><td>No action required. The machine learning model requires additional HTTP requests (and additional time).</td></tr><tr><td>Enforce Schema</td><td>It is now recommended to use Schema Validation in Prevent mode. The suggested schema to use is the recommended schema to be used by Schema Validation.<br>Activate Schema Validation with the latest suggested schema following a review. <br>A recommended good practice is to activate Schema Validation in Detect mode for a few days, review the logs regarding traffic that would've been blocked by it, and then moving to Prevent.</td></tr><tr><td>Review Schema</td><td>Schema Validation is active and set to Prevent.<br>It is recommended to replace the schema used by Schema Validation with the latest schema suggestion.</td></tr><tr><td>Schema is Enforced</td><td><p>No action required.</p><p>Well Done! The asset is protected and the latest learned schema is enforced. The are no further suggested changes.</p></td></tr><tr><td>Review Tuning Suggestions</td><td>Improve the accuracy of the suggested schema by answering the Tuning suggestions generated by the learning mechanism.</td></tr></tbody></table>

{% hint style="info" %}
In the example below the **Recommendation** is to start enforcing the detected schema.
{% endhint %}

<figure><img src="https://2760087783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEWA4nfgNrSRL8dA6Kap7%2Fuploads%2Fp3B3GwUtV4JvJf3vgF9P%2Fappsec-api-discovery-assets-learn-recommendation.png?alt=media&#x26;token=82aefa36-2c46-4fb0-b4c6-f9d7217cc192" alt=""><figcaption></figcaption></figure>

## Viewing Suggested Schema

As the iterative learning model sees more and more traffic, a schema is built.

This learning process never stops, even after reaching the most mature level of the learning model, corresponding with the ever-changing life cycle of a web server, as new APIs are added and sometimes deprecated, causing a need to change the enforced schema.

<figure><img src="https://2760087783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEWA4nfgNrSRL8dA6Kap7%2Fuploads%2FRL1fDVBTHRJo8PIF7UI7%2FAPIDiscoveryLearn3.png?alt=media&#x26;token=8dee3659-7957-4684-a934-53fb4f4df4e1" alt=""><figcaption></figcaption></figure>

* It is possible to view the schema in a similar way to the view within the know API exploration UI tool Swagger. Click **Open Schema**:

<figure><img src="https://2760087783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEWA4nfgNrSRL8dA6Kap7%2Fuploads%2FN6CzxKn8sWBfUNhqbba1%2Fappsec-api-discovery-assets-learn-show-schema.png?alt=media&#x26;token=483a8bae-70ac-442c-9dbb-adce8079851d" alt=""><figcaption></figcaption></figure>

* It is possible to download the schema in YAML format. Click **Download Schema.**
* Data for each endpoint includes:
  * Change status compared to the previously learned schema version.
  * Usage of sensitive data in requests to this endpoint.
  * Counts for requests and unique sources that use this endpoint.
  * Indication of public API (if it was accessed from other public addresses)
  * First and Last seen dates (this data is saved beyond 7 days).

## Tuning Suggestions

The [Contextual Machine Learning](https://waf-doc.inext.checkpoint.com/concepts/contextual-machine-learning) model may ask to review certain events, also called **Tuning Suggestions**. Providing feedback to these suggestions is not mandatory as the engine is capable of learning by itself. However doing this, allows the machine learning engine to reach a higher maturity level and therefore a better accuracy faster based on human guidance.&#x20;

#### Step 1: Review Tuning Suggestions

1. Go to **Cloud->Assets** and select the Asset you want to review.
2. Select the **Learn** tab. This tab, at its bottom, shows **Tuning Suggestions** and **Tuning Decisions**.
3. Review the proposed **Tuning Suggestions**.

<figure><img src="https://2760087783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEWA4nfgNrSRL8dA6Kap7%2Fuploads%2FtDGQlZkI7hYxCb1mWjYu%2FAPIDiscoveryLearn2.png?alt=media&#x26;token=85cbb8c7-751c-4728-975a-5b734fb823ab" alt=""><figcaption></figcaption></figure>

#### Step 2: Provide feedback to the proposed Tuning Suggestions

1. Click on the **Yes** or **No** button next to the line of the Tuning Suggestion. Your Tuning Suggestion now moves to the **Tuning Decisions** list, where it is also possible to undo the decision.

<figure><img src="https://2760087783-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEWA4nfgNrSRL8dA6Kap7%2Fuploads%2FPWYF0lLvXqHVrkVq3V2b%2Fappsec-api-discovery-assets-learn-tuning-decisions.png?alt=media&#x26;token=38871438-4832-4259-814a-e02d06cca871" alt=""><figcaption></figcaption></figure>

#### Step 3: Review the new recommended action if exists

1. Go to [Step 2: Learn the recommended action](#step-2-address-the-recommended-action) of the previous section to learn what to do next to improve the learning process.