Request-Response Processing Mode

This document covers topics which are specific to Request-Response processing mode. Please read the introduction to scenario authoring to learn basics of scenario authoring.

Defining input and output from the Request - Response scenario

Unlike in the Streaming processing mode, there is no Schema Registry which would store data schemas - request and response schemas in our case. Still, the schema of the request and response ("input" and "output") need to be declared to Nussknacker; they are defined alongside the scenario (as the scenario property). The "language" used to define schemas is called JSON Schema. Nussknacker uses those schemas to understand how the request and response should look, assist you with hints and validate expressions you write.

Click kebab menu icon (three vertically aligned dots next to the scenario name) on the right panel and access the properties of the scenario to view or edit the input and output schemas of the scenario. The same Input schema and Output schema (and the Slug) can also be edited directly in the request source node; changes made there are saved as the scenario properties. When the request source uses a bodyless method (GET or DELETE), its input is declared by the node's Query parameters instead, so the node does not show Input schema.

The output schema is a map from HTTP status code to that code's JSON Schema, with a required default entry used for any status code without its own schema:

{
  "default": { "type": "object", "properties": { "name": { "type": "string" } } },
  "404": { "type": "object", "properties": { "message": { "type": "string" } } }
}

A response sink is validated against - and its response is encoded with - the schema of its selected HTTP status code, falling back to default. The keys must be status codes supported by the HTTP status code sink parameter. The generated OpenAPI definition describes each status code with its own schema.

The schemas are written as JSON Schema text; the table-based JSON schema builder is not used here. The fields that the output schema defines for a response sink can be filled with the Data Mapper.

Integrating scenario into the automation workflows

Click kebab menu icon and access the properties of the scenario to view the integration details of the scenario:

• the example curl based invocation
• OpenAPI interface definition
• Swagger UI.
• Basic Auth credentials

The Integration section opens with an Access line saying who may call the scenario - anyone, the configured Basic user, or a holder of a Nussknacker API token - and the example curl carries the matching credentials. See Who may call the scenario for how to change it.

Note that on the first attempt to call Nussknacker scenario from Swagger UI you will be prompted to enter the credentials of your request - response scenario: the Basic Authentication credentials shown in the scenario Properties, or a Nussknacker API token when the scenario requires one. These are not your Nussknacker cloud credentials.

Who may call the scenario

The Access property of the scenario (in Properties, and under Advanced parameters of the Request node) decides who may call the deployed endpoint:

Access	Who may call the scenario
Deployment default	Whatever the installation configures: its Basic user when one is set up, otherwise anyone. The behaviour from before the property existed
Open - no token required	Anyone who reaches the endpoint; no credentials are looked at
Nussknacker API token required	A Nussknacker API token whose owner may call this scenario (Scenario.Invoke on it or its category); the installation's Basic user still passes

A change takes effect on the next deployment. A scenario requiring a token answers 401 to a call without credentials or with an unknown, revoked or expired token, and 403 to a token whose owner may not call it. Its OpenAPI definition and Swagger UI then need the same token, and the definition declares the token as its security scheme, so a client generated from it or Swagger UI's Authorize takes it.

The installation may forbid open endpoints, and requiring a token needs the Access control section of the Designer, which issues them.

A deployed Request - Response scenario can also be called by AI agents, as a tool of an MCP server hosted by Nussknacker - see MCP servers.

Calling a scenario from another scenario

To call a Request-Response scenario from another scenario, add its OpenAPI interface definition as an OpenAPI integration: copy the definition URL from the Integration section of the scenario's properties into the integration's Spec URL, and put the credentials the scenario is called with into the integration. The integration adds an enricher whose parameters are the fields of the scenario's input schema and whose result is typed by its output schema. When the called scenario's input or output schema changes, refresh the integration.

Do not call the scenario with the HTTP component and a URL typed in: its credentials would be stored in the calling scenario, and the address depends on the installation - in Nussknacker Cloud it is the instance's gateway, not localhost.

Scenario response in scenarios with split and for-each nodes

It may happen that the scenario contains parallel branches, following split node. This ifs common in situations when testing multiple 'hypothesis' is important and these 'hypothesis' are independent of each other. Performing this 'hypotheses testing' sequentially yields much higher response times than when the hypothesis are processed in parallel.

If parallel branches end with response nodes and more than one response is generated (e.g there is no filtering after split), the only response which is returned is the one which is generated first chronologically. There is no way to determine which one will be generated first. If all responses are important to you, you need to take additional measures - use the collect node to merge the branches and collect data records coming from individual branches into a list.

If you use for-each node and need to collect all the results into a list of values, use collect node.

Finally, if no response is generated (e.g. after filtering), an error is returned (in the future this behavior may change).

Request - Response specific components

Request

See this document for the details of the Request component.

Response

See this document for the details of the Response component.

Kafka service

Request-Response scenarios can also write messages to Kafka with the kafka service. It becomes available when the liteRequestResponseKafka.jar component set is on the model classpath and the model configuration contains the kafka section (bootstrap servers, schema registry) - the same configuration as for the streaming Kafka components. The parameters (Topic, Schema version, Key, Value) work exactly like in the streaming Kafka sink.

The record is sent to Kafka as part of handling the HTTP request and the service returns the metadata of the written record (a record with the topic, partition, offset and timestamp fields), so the scenario can continue after the write - e.g. respond with the offset. When the write fails, the whole request fails. Delivery is at-least-once: a client retrying the HTTP request may produce duplicate records. During scenario testing in Designer no records are sent to Kafka - the service only collects the value that would be written and returns stubbed metadata (partition, offset and timestamp set to -1).

Collect component

See here for description of the Collect component.

Scenario properties

Click kebab menu icon (three vertically aligned dots next to the scenario name) on the right panel and access the properties of the scenario.

Scenario properties explained

Property name	Description
Name	Scenario name
Input schema	See Defining input and output from the Request - Response scenario for explanation
Output schema	See Defining input and output from the Request - Response scenario for explanation
Slug	Change slug to modify the url of your scenario and of its interface definition
Integration	See here
Access	Who may call the scenario