Product Documentation
ADC
14.1 - Current Release 13.1 13.0 12.1
View PDF

Import API Specification

September 24, 2024
Contributed by: 
C B

API specification defines the design of an API, including endpoints, methods, parameters, and data formats. The import API specification capability allows you to import the open API specification, which is generally used to describe the REST API. When the Web App Firewall performs a validation check on a user’s request for an API-based web service, it validates the request against the schema specified in the API specification file for that web service. NetScaler supports schema validations for a REST API with payload being application JSON and ProtoBuf for gRPC API requests.

Note:

Starting from NetScaler release 14.1 build 34.x, NetScaler supports content validation for application/x-www-form-urlencoded body content.

NetScaler supports the following specification formats:

  • Open API - Swagger 2.0, OAS 3.0,3.1
  • ProtoBuf - v3 and v2

Manage API specification files

You can validate incoming API traffic against the imported API specification by assigning it to a profile and setting a relaxation rule to either block or allow the traffic. You can also use the imported API specification in creating policy expressions. Importing an API specification consists of two steps:

  1. Import the API specification - Import an API specification to NetScaler through a URL or from the system.
  2. Add the API specification to NetScaler - When you add an API specification to NetScaler, the file is validated, converted into an internal format, and an API specification entity is created. The API specification entity created will be used in policy expressions and Web App Firewall profiles.

Note:

Ensure that the uploaded Open API Swagger 2.0, OAS 3.0, and 3.1 specification files do not contain any references to external files. If you need to use details from an external file, consolidate the information into a single file using open-source tools and then upload it.

Manage API specification files using the CLI

The following parameters are used in the CLI commands:

  • Name - Name of the API specification file that is uploaded.
  • Source - URL (protocol, host, path, and name) for the location to store the imported specification file.
  • Spec Name - The name of the entity that is created from the uploaded API specification.
  • Type - Input format of the API specification. Default Value: OAS

To import an API specification file, type:

import api specFile <name> <src>

Example:
import apispec testapispec.json http://www.example.com/testapispec.json

To add an API specification file, type:

add api spec <Name> -File <string> -Type <string>

Example:
add api spec testapispec -File testapispec.json -Type OAS

To update an API specification file, import a new specification file that needs to be updated.

At the command prompt, type:

update api spec <specName> -File <string> -Type <string>

Example:
update api spec testapispec -File testapispec.json -Type OAS

Note:

If the type attribute is not specified, OAS is the default type.

To view all the endpoints, type:

show api spec <specName>

Example:

show api spec testapispec

To delete the API specification, type:

rm api spec <specName>

Example:

rm api spec testapispec

Note:

Before removing the API specification, make sure it is not being used by any profile or policy.

Manage API specification files using the GUI

  1. Navigate to Security > NetScaler Web App Firewall > Imports.
  2. On the Imports page, select the API Spec Import Page tab, and then click Add.
  3. On the API Spec Import Object page, select any one of the following options for the Import From parameter:
    1. URL: A web URL on a website accessible to the appliance.
    2. File: A file on a local or networked hard disk or other storage device.
  4. Click Continue.
  5. On the API Spec Import Object page, enter the following details:
    1. API Spec Name – The name of the entity that is created from the uploaded API specification. Note: Both the API file name and the API Spec Name entered should be the same.

    2. API Spec Type – Select the type of specification.

      Types: REST (OpenAPI/Swagger), and gRPC(PROTO).

      Default Type: REST (OpenAPI/Swagger)

    3. Click Done.

The newly added entity is listed in the Imports page under the API Spec Import Page tab.

View the statistics of API specification and API endpoints

You can view the following statistics for all the API specifications and API endpoints:

  • API specifications hits - Requests matching any endpoint of the API specification.
  • API specification successful validations - Requests matching any endpoint of the API specification and in conformance with the API schema.
  • API specification unmatched requests - Requests not matching any endpoint of the API specification.
  • API endpoints hits - Requests matching a specific endpoint.
  • API endpoints successful validations - Requests matching a specific endpoint and in conformance with the API schema.

View API specifications and API endpoint statistics using the CLI

At the command prompt, type:

stat apispec <apispec name>

Example

stat apispec testapispec

View API specifications and API endpoint statistics using the GUI

  1. Navigate to Security > NetScaler Web App Firewall > Imports.

  2. On the Imports page, select the API Spec Import tab, and then click Statistics.

    The API specification summary is displayed.

  3. To view the endpoint summary, click any of the API specifications.

    The API endpoint summary is displayed for the selected API specification.

Import API Specification
September 24, 2024
Contributed by: 
C B
September 24, 2024
Contributed by: 
C B

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.