Overview
API Discovery allows for the automatic detection of potential APIs, in addition to providing a simpler onboarding to API protection. API Discovery allows you to quickly recognize and manage your APIs (including legacy and shadow APIs). This feature is available to use on any site running WAF services, not limited to API-only sites.
API Discovery and protection are provided for APIs that are both public and private. Public APIs are published for public consumption and are available for anyone to use, while private APIs are only available to authorized users.
API Discovery protects REST APIs only. SOAP and other styles are not included.
Navigating the Portal
To get started, navigate to the API Discovery menu, which is located on the left-side navigation. Here you'll see four tabs listed at the top of the page:
- API Baseline
- Potential APIs
- Scan History
- Settings
More details about each section are explained below.
API Baseline
This is where your protected API endpoints are listed. You can group them as you see fit for organizational purposes. This is also where one of the methods for onboarding new API endpoints is located.
Adding an API
To add a new API endpoint from the API Baseline tab:
- Click the Add an API button on the top right corner of the page. This will open up a pop up menu on the right side of the page.
- Enter the Scheme, Method and Endpoint.
- (Optional) Select the Version, API Group and Tags.
- If you are uploading an API Specifications file, it must be in YAML or JSON format.
- Click Add when you are finished.
APIs that are onboarded to the platform through manual entry via the API Baseline tab will automatically be moved to a status of confirmed on the API Baseline tab.
Viewing Details
Click the three dots to the right-hand side of each API endpoint line item to view the endpoint details or edit the API path.
Selecting View Details will open up a menu that displays additional information about your existing endpoint. From here you can edit the endpoints groups and tags or change its Status.
An endpoint can have one of the following statuses:
- Potential - These are endpoints that have been onboarded into the system through a network scan and are awaiting be marked as a confirmed API or not an API. It's up to the user to confirm whether or not this is a valid API.
- Confirm - Indicates that an endpoint is a valid API and should be protected. All endpoints that were manually onboarded into the tool will automatically be assigned this status. This can be changed.
- Not an API - Indicates that a potential endpoint is not a valid API and does not need additional protection. Users can manually assign this status to endpoints that were falsely scanned during a network scan.
- Delisted - API endpoint was originally found in an uploaded, scanned Swagger file, but subsequently missing after a later scan.
When manually entering or editing a path, you can use curly braces to signify query string parameters. e.g., /api/v1/stacks/{stack_id}/sites/{site_id}.
Potential APIs
When the API Discovery feature performs a network scan, the endpoints that are detected populate in this section. Here is where you can manage the status of these endpoints and determine whether or not they are a confirmed endpoint or not an API.
Once an API endpoint is moved to either confirmed or not an API, it will be removed from this tab and placed in the API Baseline tab.
Scan History
The Scan History section provides users with a list of all of the endpoints that were scanned using API Discovery, either by way of a network scan or Swagger file scan, sorted by date/time. This section also provides you with information as to whether or not the scan was successful, or resulted in errors. If an error did occur, a message with further details is provided in the Message column.
You can also refetch the results populated here should a new scan have occurred while you were on this page. Results will be automatically fetched at the designated time intervals selected on the Settings tab for each scan type.
Settings
The Settings section provides two additional manual onboarding mechanisms as well as provides users with the ability to change API Specification scan and Network scan intervals.
API Base Path
If your site uses an API that's implemented on the same domain, you need to add it here. This defines the API communication path that the system will expect API requests from.
API Specifications File
Use API Discovery to parse an uploaded JSON or YAML Swagger file for API endpoints. You can either point to the URL of the Swagger file on the Path tab, or you can upload the Swagger file from the Upload tab. Once the scan is complete, potential endpoints will populate in the API Baseline list.
Selecting the Start Swagger Scan button will trigger a scan of the listed paths or files for APIs.
API endpoints onboarded to the tool from either of these two methods will automatically be moved to a status of confirmed on the API Baseline tab.
Uploading a Swagger file can significantly reduce the work needed for the classification of potential APIs, as this will automatically classify most of the endpoints that comprise the API Baseline.
Scan Settings
You can toggle the two settings in this section on/off at any time. More information about each setting is explained below.
Network Scans
Set an interval for when API Discovery will scan all of your site's URLs and detect new potential API endpoints.
API Specification Scans
Set an interval for when API Discovery will scan your uploaded API Specification file or specified API paths to see if any new endpoints were added or if any preexisting endpoints were removed (Delisted).