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.

API server definition, single server

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 Use cases 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

Use cases

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

API server definition, single server

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 Use cases 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"}'