Request-Response

Overview

Depending on your network topology after you deploy a Request-Response scenario, there should be either a k8s service or ingress resource allowing you to connect to the scenario.

When you use default source and sink, you can interact with REST API provided by before mentioned service or ingress. The HTTP method is chosen in the method parameter of the request source: POST (the default), GET, PUT, DELETE or PATCH. A request that uses a different method than the scenario's source is answered with 405 Method Not Allowed.

A GET or DELETE scenario reads its input from query parameters instead of a request body. Those scenarios declare their parameters in the queryParameters field of the request source, one entry per parameter, and the incoming values are coerced to the declared types. Only scalars (including string enums) and lists of scalars can be declared, because a query string cannot express anything deeper.

POST, PUT and PATCH read a JSON body described by the inputSchema scenario property, as before. They can additionally declare queryParameters next to the body: the query values are merged into #input alongside the body fields. The inputSchema must then be a plain object, and a query parameter must not share its name with a body property - the Designer rejects both at validation time, so body and query values can never collide at runtime.

Connection

In case of service you can trigger your scenario with example curl command:

curl -X POST -d "payload_based_on_input_schema" 'http://<scenario_slug>'

For ingress configuration it looks quite similar:

curl -X POST -d "payload_based_on_input_schema" 'http://<ingress_domain>/<scenario_slug>'

A GET scenario is invoked with its input in the query string:

curl 'http://<ingress_domain>/<scenario_slug>?first=John&last=Doe'

Integration section in the Designer

The request source window can show an Integration section with the scenario's endpoint, a ready-to-copy cURL example matching the source's method (a body sample generated from the input schema for POST, PUT and PATCH, a query string built from the declared parameters for GET and DELETE), a Swagger UI link, the OpenAPI definition URL and the Basic Auth credentials.

It is enabled by an integrationInfo section in the model config of the Request-Response processing type:

modelConfig {
  integrationInfo {
    serviceUrlPattern: "https://gateway.example.com/{slug}"
    security.basicAuth {
      user: "publisher"
      password: "secret"
    }
  }
}

{slug} in serviceUrlPattern is replaced with the scenario's slug. The security.basicAuth part is optional - when present, the credentials are rendered (masked) and included in the cURL example.

Embedded engine

When Request-Response scenarios run on the embedded engine (the lite-embedded scenario type, on its own or as one of the deployment targets of a scenario type that configures deploymentConfig.targets), they are served by a single HTTP listener opened by the designer itself, configured by the http section of the scenario type's deployment configuration. There is no per-scenario service or ingress: every scenario is available under its own slug at http://<http.interface>:<http.port>/scenario/<scenario_slug>.

Since all scenarios share one listener, it also exposes the list of the slugs currently served by it:

curl 'http://<http.interface>:<http.port>/slugs'
["scenario_slug_1","scenario_slug_2"]

This endpoint lists every scenario served by the listener, so it is guarded by the same request-response.security.basicAuth credentials as the scenario invocations. When no credentials are configured it is open, just like the invocation endpoints.

Swagger UI

For each saved scenario Swagger UI will be available at http://<ingress_domain>/<scenario_slug>/swagger-ui (ingress case). In the service case, Swagger UI will be available at http://<scenario_slug>/swagger-ui.

OpenAPI interface definition

For each deployed Request-Response scenario an OpenAPI interface definition will be available at http://<ingress_domain>/<scenario_slug>/definition (ingress case). In the service case it will be available at http://<scenario_slug>/definition.

You can see example definition below:

Scenario OpenAPI definition

{
  "openapi" : "3.1.0",
  "info" : {
    "title" : "dsw-rr",
    "version" : "1"
  },
  "paths" : {
    "/" : {
      "post" : {
        "description" : "**scenario name**: dsw-rr",
        "tags" : [
          "Nussknacker"
        ],
        "requestBody" : {
          "required" : true,
          "content" : {
            "application/json" : {
              "schema" : {
                "type" : "object",
                "nullable" : false,
                "properties" : {
                  "input" : {
                    "type" : "object",
                    "nullable" : false,
                    "required" : [
                      "first",
                      "last"
                    ],
                    "properties" : {
                      "last" : {
                        "type" : "string",
                        "nullable" : false
                      },
                      "first" : {
                        "type" : "string",
                        "nullable" : false
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "produces" : [
          "application/json"
        ],
        "consumes" : [
          "application/json"
        ],
        "summary" : "dsw-rr",
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "type" : "object",
                  "properties" : {
                    "input" : {
                      "type" : "object",
                      "properties" : {
                        "first" : {
                          "type" : "string"
                        },
                        "last" : {
                          "type" : "string"
                        }
                      },
                      "required" : [
                        "first",
                        "last"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}