Skip to main content
Version: Current

OpenAPI

Overview​

OpenAPI is a specification for machine-readable interface definition for describing, producing, consuming, and visualizing RESTful web services. Nussknacker can read definition of an OpenAPI interface and generate an enricher component for each operation defined in the interface (service) specification.

Nussknacker supports OpenAPI specification versions 2.x and 3.x (note: 2.x is considered deprecated).

note

Integrations are defined in the UI in the Integrations view of the Designer's side menu, available in Nussknacker Cloud and in Enterprise deployments. If you use the OSS edition, check the Open Source version integrations documentation for details on how to configure integrations in configuration files.

Integration parameters​

ParameterDescription -
Integration nameUnique name for the integration
Spec URLURL of the OpenAPI interface definition. It contains definition of the service you want to interact with.
Server URLThe URL of the service. If not specified, the URL of the service is taken from the OpenAPI interface definition.
API KeyAPI key that will be passed to the service via header, query parameter or cookie, as indicated in the OpenAPI interface definition
UsernameUsername for Basic authentication, sent with the password on every call.
PasswordPassword for Basic authentication.

The definition is fetched without credentials. When its server answers 401 asking for Basic or Bearer authentication, it is fetched again with the Username and Password, or with the API Key as a bearer token. The server must name the scheme in the WWW-Authenticate header of its 401: one without it, or one asking only for other schemes, is reported as an error and not retried. The credentials go to the server of the Spec URL, also when it is another than the one of the Server URL, so use a Spec URL you trust with them. OAuth2 client credentials are not used to fetch the definition: with both an API Key and OAuth2 configured, a Bearer challenge gets the API Key.

Request-Response scenarios of this instance​

The OpenAPI · Nu scenarios tile turns request-response scenarios of the same Nussknacker instance into enrichers, without copying their definition URLs and credentials. An instance has one such integration, holding one list of scenarios: the tile adds it once and edits it from then on. Pick the scenarios from the list; each one becomes an enricher labelled with the scenario's name, typed by the scenario's input and output schema, and calling the scenario. A scenario is picked once, so its enricher has one name.

The list offers the scenarios of the categories you can see. The scenarios of other categories picked by someone else stay picked and out of your sight: your save keeps them. A scenario needs a slug set in its properties - a new one gets it when created: without it every engine derives its own and the address is unknown, so the scenario cannot be picked. Scenarios of different processing types may share a slug, but the address below gives them one place to be called at, so only one of them can be picked. A scenario serves its OpenAPI definition only while it is deployed, and a node using its enricher asks to deploy the scenario until it is. The enricher offers the scenario's own operation only, not the resume operation of a scenario paused at an interaction node.

The instance configures where the scenarios are called, in the Designer configuration. This address must be reachable from the Designer and from every engine that runs scenarios using the enrichers, so it is usually an internal one, not the address shown in a scenario's Integration panel:

configurator {
requestResponseScenarios {
serviceUrlPattern: "http://designer:8181/scenario/{slug}"
# optional, when the scenarios require Basic authentication
auth { username: "publisher", password: "<password>" }
}
}

The enrichers call this address, also when a scenario's OpenAPI definition names other servers.

Without this section the Designer takes the address, and the Basic user, from the integrationInfo of the request-response model - the address a scenario's Integration panel shows. That serves where the Designer and the engines reach the published address too, as they do behind one gateway; where they do not, set the section. Set it also when several request-response models publish their scenarios under different addresses or ask for different users: the Designer does not choose between them, and the integration stays unavailable. With an address taken from the models the list offers the scenarios of the models that publish it; a model without integrationInfo is left out, and its scenarios appear only once the section is set. With neither, the tile says so and the integration cannot be saved. Basic authentication is the only one the enrichers can send. When the list is saved, the definition of each picked scenario that is deployed is read the way its enricher reads it, and what fails - an address the Designer cannot reach, an operation that needs auth while it is not set, or needs another authentication - is shown as a warning. A warning does not keep the list from being saved.

The integration stores scenario names and looks their slugs up whenever the components are generated: when any integration is saved, and when the Designer starts. A changed slug is picked up then. An archived scenario loses its enricher; a renamed one too, until it is picked again under its new name. A change of a scenario's input or output schema reaches the enricher once its definition is read again.

Additional info​

Nussknacker applies following rules when mapping OpenAPI operations to enrichers:

  • Parameters (path, query of header) are used to define enricher parameters
  • If specification declares body parameter as object, we expand to parameter list
  • We expect operation to define 200/201 response, returned object is the one that is the result of enricher
  • We map 404 HTTP code to null value of enricher
  • We use externalDocs.url to extract documentation link

Table below describes data types that OpenAPI integration handles:

OpenAPI TypeOpenAPI FormatType in Nussknacker
booleanBoolean
stringString
stringdate-timeLocalDateTime
integerLong
integerint32Integer
integerint64Long
numberBigDecimal
numberdoubleDouble
numberfloatDouble
arrayarray
map/objectrecord

OpenAPI integration can handle schema references. However, we don't support recursive schemas at the moment. Recursive schema occurrences will be replaced with Unknown type.

For objects and maps we use properties to define structure. For arrays, we use items to define type of elements.