Skip to main content

Generate a WAAS API Specification Object

POST 
/api/v33.02/policies/firewall/app/apispec
x-prisma-cloud-target-env: {"permission":"policyWAAS"}

Resolves the endpoints defined in an OpenAPI/Swagger specification and returns a waas.APISpec object.

The waas.APISpec object can be included in the body of a subsequent call to the PUT api/v1/policies/firewall/app/app-embedded endpoint to define an app that WAAS monitors and protects.

To invoke this endpoint in the Console UI:

  1. Navigate to the Defend > WAAS > App-Embedded page.
  2. Click Add rule.
  3. Enter the details for the new rule and click Add new app.
  4. On the App definition tab, click the Import button and select an OpenAPI/Swagger specification file.

Note: You can use a YAML or JSON format for the OpenAPI/Swagger specification.

cURL Request​

Refer to the following example cURL command that imports an API from an OpenAPI/Swagger specification:

$ curl 'https://<CONSOLE>/api/v<VERSION>/policies/firewall/app/apispec' \
  -k \
  -X POST \
  -u <USER> \
  -H 'Content-Type: application/json' \
  -d \
'{
  "swagger": "2.0",
  "info": {
    "version": "2021.7.28",
    "title": "Book API",
    "description": "A simple API for books.",
    "contact": {
      "name": "John Smith",
      "email": "test.email@email.com",
      "url": "http://mywebsite.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host": "api.mywebsite.com",
  "basePath": "/api",
  "schemes": [
    "http"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/books": {
      "get": {
        "description": "Returns a list of books.",
        "operationId": "findBooks",
        "responses": {
          "200": {
            "description": "Success response",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Book"
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Book": {
      "allOf": [
        {
          "required": [
            "id"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "format": "int64"
            }
          }
        }
      ]
    },
    "Error": {
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}'

A successful response returns a waas.APISpec object containing the API specification that was imported.

Responses​

APISpec is an API specification

Schema
    description string

    Description of the app.

    effect waas.Effect (string)

    Possible values: [ban,prevent,alert,allow,disable,reCAPTCHA]

    Effect is the effect that will be used in the rule

    endpoints object[]

    The app's endpoints.

  • Array [
    • basePath string

    Base path for the endpoint.

    exposedPort integer

    Exposed port that the proxy is listening on.

    grpc boolean

    Indicates if the proxy supports gRPC (true) or not (false).

    host string

    URL address (name or IP) of the endpoint's API specification (e.g., petstore.swagger.io). The address can be prefixed with a wildcard (e.g., *.swagger.io).

    http2 boolean

    Indicates if the proxy supports HTTP/2 (true) or not (false).

    internalPort integer

    Internal port that the application is listening on.

    tls boolean

    Indicates if the connection is secured (true) or not (false).

  • ]
    • fallbackEffect waas.Effect (string)

    Possible values: [ban,prevent,alert,allow,disable,reCAPTCHA]

    Effect is the effect that will be used in the rule

    paths object[]

    Paths of the API's endpoints.

  • Array [
    • methods object[]

    Supported operations for the path (e.g., PUT, GET, etc.).

  • Array [
    • method string

    Type of HTTP request (e.g., PUT, GET, etc.).

    parameters object[]

    Parameters that are part of the HTTP request.

  • Array [
    • allowEmptyValue boolean

    Indicates if an empty value is allowed (true) or not (false).

    array boolean

    Indicates if multiple values of the specified type are allowed (true) or not (false).

    explode boolean

    Indicates if arrays should generate separate parameters for each array item or object property.

    location waas.ParamLocation (string)

    Possible values: [path,query,cookie,header,body,json,xml,formData,multipart]

    ParamLocation is the location of a parameter

    max double

    Maximum allowable value for a numeric parameter.

    min double

    Minimum allowable value for a numeric parameter.

    name string

    Name of the parameter.

    required boolean

    Indicates if the parameter is required (true) or not (false).

    style waas.ParamStyle (string)

    Possible values: [simple,spaceDelimited,tabDelimited,pipeDelimited,form,matrix,label]

    ParamStyle is a param format style, defined by OpenAPI specification It describes how the parameter value will be serialized depending on the type of the parameter value. Ref: https://swagger.io/docs/specification/serialization/ https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#style-examples

    type waas.ParamType (string)

    Possible values: [integer,number,string,boolean,array,object]

    ParamType is the type of a parameter, defined by OpenAPI specification Ref: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types

  • ]
  • ]
    • path string

    Relative path to an endpoint such as "/pet/{petId}".

  • ]
    • queryParamFallbackEffect waas.Effect (string)

    Possible values: [ban,prevent,alert,allow,disable,reCAPTCHA]

    Effect is the effect that will be used in the rule

Loading...