Fortinet black logo

Administration Guide

Use cases

Use cases

The following shows the OpenAPI file, explanations on the API call validation, and valid/invalid API examples for each use case.

  1. API server definition, single server

  2. OpenAPI file

    openapi: 3.0.0

    info:

    version: 1.0.0

    title: Swagger Petstore

    license:

    name: MIT

    servers:

    - url: 'HTTP://petstore.swagger.io/v1'

    paths:

    /pets:

    get:

    summary: List all pets

    operationId: listPets

    tags:

    - pets

    parameters:

    - name: limit

    in: query

    description: How many items to return at one time (max 100)

    required: false

    schema:

    type: integer

    responses:

    '200':

    description: A paged array of pets

    content:

    application/json:

    schema:

    type: string

    Explanations:

    In this example, FortiWeb validates the API call from the following fields:

  • The API call is based on host/url: HTTP://petstore.swagger.io/v1.
  • The API call path is /pets, so the full host/url is HTTP://petstore.swagger.io/v1/pets.
  • The API call method is "GET".
  • The parameter "limit" is not required, and it must be integer type.
  • The "query" means the parameter must be carried in URL parameter after "?".

Valid API request example:

curl HTTP://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json"

Invalid API request example:

curl HTTP://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json"

  • API server definition, multiple servers
  • OpenAPI file

    openapi: 3.0.0

    info:

    version: 1.0.0

    title: Swagger Petstore

    license:

    name: MIT

    servers:

    - url: 'HTTP://petstore.swagger.io/v1'

    - url: 'HTTP://petstore2.com/v1'

    - url: 'HTTP://petstore3.com/v1'

    paths:

    /pets:

    get:

    summary: List all pets

    operationId: listPets

    tags:

    - pets

    parameters:

    - name: limit

    in: query

    description: How many items to return at one time (max 100)

    required: false

    schema:

    type: integer

    responses:

    '200':

    description: A paged array of pets

    content:

    application/json:

    schema:

    type: string

    Explanations:

    In this example, multiple server URLs are defined:

    - url: 'HTTP://petstore.swagger.io/v1'

    - url: 'HTTP://petstore2.com/v1'

    - url: 'HTTP://petstore3.com/v1'

    It means the three URLs can all match the request host/URL. In another word, HTTP://petstore.swagger.io/v1/pets, HTTP://petstore2.com/v1/pets, and HTTP://petstore3.com/v1/pets all match the method path.

    Valid API request examples:

    curl HTTP://petstore2.com/v1/pets?limit=123 -H "Accept: application/json"

    curl HTTP://petstore3.com/v1/pets?limit=456 -H "Accept: application/json"

    Invalid API request examples:

    curl HTTP://petstore2.com/v1/pets?limit=abc -H "Accept: application/json"

  • API path validation
  • OpenAPI file:

    openapi: 3.0.0

    info:

    version: 1.0.0

    title: Swagger Petstore

    license:

    name: MIT

    servers:

    - url: 'HTTP://petstore.swagger.io/v1'

    paths:

    /pets/{petId}:

    get:

    summary: List all pets

    operationId: listPets

    tags:

    - pets

    parameters:

    - name: petId

    in: path

    description: How many items to return at one time (max 100)

    required: false

    schema:

    type: integer

    responses:

    '200':

    description: A paged array of pets

    content:

    application/json:

    schema:

    type: string

    Explanations:

    The "path" indicates the location of the API. The server URL and path must be combined to obtain the full domain/URL of an API call.

    In this example, the definition of the "path" is a template /pets/{petId}. petId is a parameter and it is an integer, which is carried n the URL path.

    The request domain/URL below can match the API paths:

    HTTP://petstore.swagger.io/v1/pets/123

    Valid API request example:

    curl HTTP://petstore.swagger.io/v1/pets/123 -H "Accept: application/json"

    Invalid API request example:

    curl HTTP://petstore.swagger.io/v1/pets/abc -H "Accept: application/json"

  • API Parameter validation
  • The parameter validation involves complex serialized rules and attributes settings, and the following examples show how our parameter validation works.

    • The location of the parameter
      The location of the parameter is described in "in" attribute. According to OpenAPI Specification, 4 locations are supported, query, header, path, and cookie. See API server definition, single server for how to use parameter in "query" location, and API path validation for "path" location. The following example shows how to use parameter in "header" location.

      OpenAPI file

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: header

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: integer

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type: string

      Explanations:

      In this example, the parameter "limit" is carried by HTTP header. The type is integer.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets/ -H "Accept: application/json" -H "limit: 123"

      Invalid API request examples:

      curl HTTP://petstore.swagger.io/v1/pets/ -H "Accept: application/json" -H "limit: abc"

      curl HTTP://petstore.swagger.io/v1/pets/?limit=123 -H "Accept: application/json"

      curl HTTP://petstore.swagger.io/v1/pets/ -H "Accept: application/json"

    • The data type of the parameter
      Besides "integer" and "string", FortiWeb also supports other data types: number and boolean. The following example shows the type boolean.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: boolean

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type: string

      Explanations:

      The data type is boolean, the value must be either true or false.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=true -H "Accept: application/json"

      Invalid API request examples:

      curl HTTP://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json"

    • The HTTP methods
      FortiWeb supports HTTP methods, GET, POST, DELETE, and PUT.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      post:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: boolean

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      Explanations:

      In this example, the HTTP method POST is used.

      Valid API request example:

      curl -X POST HTTP://petstore.swagger.io/v1/pets?limit=false -H "Accept: application/json"

      Invalid API request example:

      curl -X POST HTTP://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json"

    • Parameter type: array
      FortiWeb also supports some complex data types, such as "array" and "object".
      The "array" type can be a list of items described by simple types, such as a list of integers or strings.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: array

      items:

      type:integer

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      Explanations:

      In this example, parameter type "array" is used. Parameters of the same name with be added in an array.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=1&imit=2 -H "Accept: application/json"

      Invalid API request example:
      curl HTTP://petstore.swagger.io/v1/pets?limit=1&imit=abc -H "Accept: application/json"

      Here is an example when the object type is an aggregation of multiple simple type items.

      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      explode:false

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: object

      required:

      - param 1

      - param 2

      properties:

      para1:

      type:integer

      para2:

      type:integer

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      Explanations:

      In "object" type, 2 items are declared, param 1 and param2, which are both integers.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=param1,1,param2,1 -H "Accept:application/json"

      Invalid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=param1,1,param2,abc -H "Accept: application/json"

    • Reference of the schema
      Sometimes, the schema of a parameter is long and inconvenient to be written under the parameter declaration. FortiWeb supports schema reference.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: true

      schema:

      $ref: '#/components/schemas/ref'

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      components:

      schemas:

      ref:

      type: integer


      Explanations:

      In this example, the schema of the parameter is not directly added to the context of the parameter declaration; instead, it declares a reference: $ref: '#/components/schemas/ref'.
      Then when parsed, the schema of the parameter will be obtained from components > schema > ref.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json"

      Invalid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json"

    • The request body
      The following example shows when you directly submit JSON data in POST body.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      post:

      summary: List all pets

      requestBody:

      content:

      - application/json:

      schema:{$ref: '#/components/schemas/pet'}

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      components:

      schemas:

      pet:

      required :

      - id

      - name

      properties :

      id :

      type: integer

      name :

      type: string

      Explanations:

      If you post the data { "id":1,"name":"test"} directly to the HTTP body, FortiWeb will validate the body directly with the schema in the OpenAPI file.

      Valid API request example:

      curl -X POST HTTP://petstore.swagger.io/v1/pets -H "Accept: application/json" -H "Content-type: application/json" -d '{ "id":1,"name":"test"}'

      Invalid API request example:

      curl -X POST HTTP://petstore.swagger.io/v1/pets -H "Accept: application/json" -H "Content-type: application/json" -d '{ "id":"abc","name":"test"}'

    Use cases

    The following shows the OpenAPI file, explanations on the API call validation, and valid/invalid API examples for each use case.

    1. API server definition, single server

    2. OpenAPI file

      openapi: 3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: false

      schema:

      type: integer

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type: string

      Explanations:

      In this example, FortiWeb validates the API call from the following fields:

    • The API call is based on host/url: HTTP://petstore.swagger.io/v1.
    • The API call path is /pets, so the full host/url is HTTP://petstore.swagger.io/v1/pets.
    • The API call method is "GET".
    • The parameter "limit" is not required, and it must be integer type.
    • The "query" means the parameter must be carried in URL parameter after "?".

    Valid API request example:

    curl HTTP://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json"

    Invalid API request example:

    curl HTTP://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json"

  • API server definition, multiple servers
  • OpenAPI file

    openapi: 3.0.0

    info:

    version: 1.0.0

    title: Swagger Petstore

    license:

    name: MIT

    servers:

    - url: 'HTTP://petstore.swagger.io/v1'

    - url: 'HTTP://petstore2.com/v1'

    - url: 'HTTP://petstore3.com/v1'

    paths:

    /pets:

    get:

    summary: List all pets

    operationId: listPets

    tags:

    - pets

    parameters:

    - name: limit

    in: query

    description: How many items to return at one time (max 100)

    required: false

    schema:

    type: integer

    responses:

    '200':

    description: A paged array of pets

    content:

    application/json:

    schema:

    type: string

    Explanations:

    In this example, multiple server URLs are defined:

    - url: 'HTTP://petstore.swagger.io/v1'

    - url: 'HTTP://petstore2.com/v1'

    - url: 'HTTP://petstore3.com/v1'

    It means the three URLs can all match the request host/URL. In another word, HTTP://petstore.swagger.io/v1/pets, HTTP://petstore2.com/v1/pets, and HTTP://petstore3.com/v1/pets all match the method path.

    Valid API request examples:

    curl HTTP://petstore2.com/v1/pets?limit=123 -H "Accept: application/json"

    curl HTTP://petstore3.com/v1/pets?limit=456 -H "Accept: application/json"

    Invalid API request examples:

    curl HTTP://petstore2.com/v1/pets?limit=abc -H "Accept: application/json"

  • API path validation
  • OpenAPI file:

    openapi: 3.0.0

    info:

    version: 1.0.0

    title: Swagger Petstore

    license:

    name: MIT

    servers:

    - url: 'HTTP://petstore.swagger.io/v1'

    paths:

    /pets/{petId}:

    get:

    summary: List all pets

    operationId: listPets

    tags:

    - pets

    parameters:

    - name: petId

    in: path

    description: How many items to return at one time (max 100)

    required: false

    schema:

    type: integer

    responses:

    '200':

    description: A paged array of pets

    content:

    application/json:

    schema:

    type: string

    Explanations:

    The "path" indicates the location of the API. The server URL and path must be combined to obtain the full domain/URL of an API call.

    In this example, the definition of the "path" is a template /pets/{petId}. petId is a parameter and it is an integer, which is carried n the URL path.

    The request domain/URL below can match the API paths:

    HTTP://petstore.swagger.io/v1/pets/123

    Valid API request example:

    curl HTTP://petstore.swagger.io/v1/pets/123 -H "Accept: application/json"

    Invalid API request example:

    curl HTTP://petstore.swagger.io/v1/pets/abc -H "Accept: application/json"

  • API Parameter validation
  • The parameter validation involves complex serialized rules and attributes settings, and the following examples show how our parameter validation works.

    • The location of the parameter
      The location of the parameter is described in "in" attribute. According to OpenAPI Specification, 4 locations are supported, query, header, path, and cookie. See API server definition, single server for how to use parameter in "query" location, and API path validation for "path" location. The following example shows how to use parameter in "header" location.

      OpenAPI file

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: header

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: integer

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type: string

      Explanations:

      In this example, the parameter "limit" is carried by HTTP header. The type is integer.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets/ -H "Accept: application/json" -H "limit: 123"

      Invalid API request examples:

      curl HTTP://petstore.swagger.io/v1/pets/ -H "Accept: application/json" -H "limit: abc"

      curl HTTP://petstore.swagger.io/v1/pets/?limit=123 -H "Accept: application/json"

      curl HTTP://petstore.swagger.io/v1/pets/ -H "Accept: application/json"

    • The data type of the parameter
      Besides "integer" and "string", FortiWeb also supports other data types: number and boolean. The following example shows the type boolean.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: boolean

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type: string

      Explanations:

      The data type is boolean, the value must be either true or false.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=true -H "Accept: application/json"

      Invalid API request examples:

      curl HTTP://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json"

    • The HTTP methods
      FortiWeb supports HTTP methods, GET, POST, DELETE, and PUT.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      post:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: boolean

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      Explanations:

      In this example, the HTTP method POST is used.

      Valid API request example:

      curl -X POST HTTP://petstore.swagger.io/v1/pets?limit=false -H "Accept: application/json"

      Invalid API request example:

      curl -X POST HTTP://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json"

    • Parameter type: array
      FortiWeb also supports some complex data types, such as "array" and "object".
      The "array" type can be a list of items described by simple types, such as a list of integers or strings.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: array

      items:

      type:integer

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      Explanations:

      In this example, parameter type "array" is used. Parameters of the same name with be added in an array.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=1&imit=2 -H "Accept: application/json"

      Invalid API request example:
      curl HTTP://petstore.swagger.io/v1/pets?limit=1&imit=abc -H "Accept: application/json"

      Here is an example when the object type is an aggregation of multiple simple type items.

      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      explode:false

      description: How many items to return at one time (max 100)

      required: true

      schema:

      type: object

      required:

      - param 1

      - param 2

      properties:

      para1:

      type:integer

      para2:

      type:integer

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      Explanations:

      In "object" type, 2 items are declared, param 1 and param2, which are both integers.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=param1,1,param2,1 -H "Accept:application/json"

      Invalid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=param1,1,param2,abc -H "Accept: application/json"

    • Reference of the schema
      Sometimes, the schema of a parameter is long and inconvenient to be written under the parameter declaration. FortiWeb supports schema reference.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      get:

      summary: List all pets

      operationId: listPets

      tags:

      - pets

      parameters:

      - name: limit

      in: query

      description: How many items to return at one time (max 100)

      required: true

      schema:

      $ref: '#/components/schemas/ref'

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      components:

      schemas:

      ref:

      type: integer


      Explanations:

      In this example, the schema of the parameter is not directly added to the context of the parameter declaration; instead, it declares a reference: $ref: '#/components/schemas/ref'.
      Then when parsed, the schema of the parameter will be obtained from components > schema > ref.

      Valid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json"

      Invalid API request example:

      curl HTTP://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json"

    • The request body
      The following example shows when you directly submit JSON data in POST body.
      OpenAPI file:

      openapi:3.0.0

      info:

      version: 1.0.0

      title: Swagger Petstore

      license:

      name: MIT

      servers:

      - url: 'HTTP://petstore.swagger.io/v1'

      paths:

      /pets:

      post:

      summary: List all pets

      requestBody:

      content:

      - application/json:

      schema:{$ref: '#/components/schemas/pet'}

      responses:

      '200':

      description: A paged array of pets

      content:

      application/json:

      schema:

      type:string

      components:

      schemas:

      pet:

      required :

      - id

      - name

      properties :

      id :

      type: integer

      name :

      type: string

      Explanations:

      If you post the data { "id":1,"name":"test"} directly to the HTTP body, FortiWeb will validate the body directly with the schema in the OpenAPI file.

      Valid API request example:

      curl -X POST HTTP://petstore.swagger.io/v1/pets -H "Accept: application/json" -H "Content-type: application/json" -d '{ "id":1,"name":"test"}'

      Invalid API request example:

      curl -X POST HTTP://petstore.swagger.io/v1/pets -H "Accept: application/json" -H "Content-type: application/json" -d '{ "id":"abc","name":"test"}'