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

API specification validation

April 15, 2024
Contributed by: 
B

API specification ensures seamless data transfer between systems through an API (Application Programming Interface). It guarantees that the data exchanged follows a predefined structure or format, thereby enhancing the overall reliability and security of the system.

An API specification defines the endpoint, schema, and parameters. Schema validation is a process that allows you to check if the incoming traffic adheres to the schema you provided in the API specification. By associating an API specification to a Web App Firewall profile, you can specify which incoming traffic is allowed, and which is either blocked or logged. Validating incoming traffic against the imported API specifications helps to ensure that network traffic is secure and compliant.

There are several API types that are commonly used in software development. These types determine how data is structured and exchanged between different software systems. NetScaler supports the following API types:

  • Representational State Transfer (REST)
  • Google Remote Procedure Call (gRPC)

API specifications define the design of an API, including endpoints, methods, parameters, and data formats. These specifications ensure consistency, interoperability, and ease of use when developing and consuming APIs. NetScaler supports the following specification formats:

  • Open API (formerly known as Swagger)
  • ProtoBuf (Protocol Buffers)

Note: You can import, add, update, and delete API specification files using the GUI or the CLI. For more information, see Imports.

Assign API Spec to a profile using CLI

Configure a Web App Firewall profile with an API specification file to validate the traffic. You can configure an action used when the validation fails using the restAction (for REST APIs) or grpcAction (for gRPC APIs) parameter.

At the command prompt, type: set appfw profile <Profile Name> -apispec <API spec entity name>

-  Profile name - The name of the profile.
-  API spec entity name - The name of the entity that is created from the uploaded API specification.

Assign API Spec to a profile using GUI

  1. Navigate to Security > NetScaler Web App Firewall > Profiles and click Add.
  2. Select the required file for an API Spec Schema and click Ok

Assign API Spec to an existing profile using GUI

  1. Navigate to Security > NetScaler Web App Firewall > Profiles
  2. Select a user-defined profile and click Edit.
  3. On the NetScaler Web App Firewall Profile page, click the Edit icon.
  4. Select the required file for an API Spec Schema and click Ok.

Configure REST and gRPC API schema validation using CLI

At the command prompt, type:

set appfw profile <profile name> -restAction [block log   none  stats]
set appfw profile <profile name> -grpcAction [block log   none  stats]
<!--NeedCopy-->

Configure REST and gRPC API schema validation using GUI

To configure or modify the REST and gRPC API schema validation:

  1. Navigate to Security > NetScaler Web App Firewall > Profiles**.
  2. Select a user-defined profile and click Edit.
  3. On the NetScaler Web App Firewall Profile page, Under the Advanced Settings section, click Security Checks.
  4. In the Security Checks section, select REST API Schema Validation or gRPC API Schema Validation and Click Action Settings.
  5. In the Actions page, set the Action parameter. You can either select or clear the option.
  6. Click Ok.

Note:

Unselect the Start URL option before configuring the security check for API Schema Validation.

Configure relaxation rule for API schema validation using CLI

Configure a relaxation rule to bypass certain traffic from being validated against the schema specified in the API specification linked with the web App Firewall profile.

To configure the relaxation rule for REST API schema validation, at the command prompt, type:

bind appfw profile <profile name> -restValidation <REST relaxation pattern> -ruleAction <Log|None>

  • REST relaxation pattern - The URL pattern for which the relaxation is applied. Patterns can include variables as well as wildcard definitions, as described in proto of Google APIs Current link: https://github.com/googleapis/googleapis/blob/master/google/api/http.proto

    The URL specified is not required to be part of the API specification.

    Note: The prefix of the pattern should have an HTTP method (ie. GET, PUT, POST, DELETE, PATCH) followed by a colon (:). Example:

    • GET:/v1/{name=messages/*} - Allows three segment URLs starting with /v1/messages and the method is GET.
    • PATCH:/v1/messages/{message_id=**} - Allows anything with /v1/messages prefix and the method is PATCH.
    • POST:/v1/lists/** - Allows anything with /v1/lists prefix and the method is POST.
    • ://engineering/**- Allows any URL that has the second segment as engineering regardless of the method.

  • Log or None - Specifies whether logs are generated for bypassed traffic matching the rule. When action is set to log, relaxed URLs and corresponding rules are dumped into system logs. When the action is set to log, the relaxed URLs and the corresponding rule are recorded in the system logs.

To configure the relaxation rule for gRPC API schema validation, at the command prompt, type:

bind appfw profile <profile name> -grpcValidation <gRPC pattern> -ruleAction <Log|None>

  • gRPC pattern - The pattern of gRPC endpoint(s) for which the relaxation is applied. The gRPC method specified is not required to be part of the API specification.

    Example:

    • citrix.api.doc.AddBook - Allows the RPC AddBook in package citrix.api.doc.
    • test.api.** - Allows all RPCs in packages, starting with test.api.
    • *.engineering.** - Allows all RPCs that have engineering as the second segment of the package name.
  • Log None - Specifies whether logs are generated for bypassed traffic matching the rule.

Configure relaxation rule for API schema validation using GUI

REST API schema validation

  1. Navigate to Security > NetScaler Web App Firewall > Profiles.
  2. Select a user-defined profile and click Edit.
  3. On the NetScaler Web App Firewall Profile page, Under the Advanced Settings section, click Relaxation Rule.
  4. Select the REST API Schema Validation and click Edit.
  5. In the REST API Schema Validation Relaxation Rules page, click Add.

  6. In the REST API Schema Validation Relaxation Rule page, specify the following details:

    1. Enabled - Select the option to enable the relaxation rule.
    2. Rest URL Pattern - Enter the URL pattern for which the relaxation is applied.
    3. REST URL Relaxation Action - Select an action.
    4. Comments- Description of the expression.
    5. Resource ID - Unique ID to identify the resource.
    6. Click Create. The newly added REST API schema validation relaxation rule is listed on the REST API Schema Validation Relaxation Rules page.

gRPC API schema validation

  1. Navigate to Security > NetScaler Web App Firewall > Profiles.
  2. On the Profiles page, select a profile and click Edit.
  3. On the NetScaler Web App Firewall Profile page, under the Advanced Settings section, click Relaxation Rule.
  4. Select the gRPC API Schema Validation and click Edit.
  5. In the gRPC API Schema Validation Relaxation Rules page, click Add.
  6. In the gRPC API Schema Validation Relaxation Rule page, specify the following details:
    1. Enabled - Select the option to enable the relaxation rule.
    2. gRPC Method Pattern - Enter the gRPC Method pattern for which the relaxation is applied
    3. REST URL Relaxation Action - Select any one of the actions.
    4. Comments- Description of the expression.
    5. Resource ID - Unique ID to identify the resource.
    6. Click Create. The newly added gRPC API schema validation relaxation rule is listed in the gRPC API Schema Validation Relaxation Rules page.
API specification validation
April 15, 2024
Contributed by: 
B
April 15, 2024
Contributed by: 
B

In this article

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