OpenAPI client flow-node

9 minute read

Overview

The OpenAPI Client (previously known as the Swagger flow-node) loads OpenAPI specifications from the ./swagger folder in your application and generates one flow-node per OpenAPI specification. The generated flow-nodes expose methods that can be used within API Builder flows for communication with the API services described in your OpenAPI specifications.

Support for OpenAPI 3.0 was added in version 2.7.0.

The OpenAPI client is installed as part of the default API Builder project; however, if you need to manually install it, you can install it from the Plugins page in the API Builder console. Alternatively, navigate to your application folder and execute the following command:

npm install --no-optional @axway/api-builder-plugin-fn-swagger

For additional getting started information, refer to the Getting Started With API Builder.

Using the OpenAPI client

During installation, the plugin will create the ./swagger folder in the root directory of your application. If the ./swagger folder already exists, it will be preserved with all of its content. To use the plugin:

1. Place your OpenAPI files (in JSON or YAML format) into the ./swagger folder.
2. Place your service icons into the ./swagger folder. This is optional but highly recommended to make your flows more readable. The icons must have the same name as the OpenAPI files for your service. Additionally, the icons must be one of the following file formats: bmp, jpeg, jpg, png, gif, tiff, or svg.
3. Execute npm start to start your application. The plugin will generate flow-nodes from your OpenAPI specifications and will be available in the Connector section of the flow-node list on the left side of the flow editor. You should see a plugin listed for each OpenAPI file successfully loaded from your ./swagger folder.

For example, here are the nodes for a service that has two OpenAPI specifications, gmail.json and petstore.yaml. For Gmail, we have included a PNG icon file. Petstore is using the default icon. For more information on using the plugin with Gmail, see Authorization: Access Gmail using OpenAPI client.

The generated flow-node for a service exposes the methods that are defined in that OpenAPI specification. For example, here we have imported a specification for Gmail, and the available flow-node methods are the individual Gmail APIs.

The methods in the flow-nodes generated by the OpenAPI client expose all the parameters defined in the OpenAPI specification, their descriptions, and the schema definitions.

Here we have three outputs. All flow-nodes generated by the OpenAPI client will have at least Default and Error outputs, with more being available if the provided OpenAPI specification advertises additional known status codes. In this case, the OpenAPI specification advertises a known 200 status code for the API corresponding to the gmail.users.messages.get method.

When executing the flow-node, if the Gmail service responds with a 200 status code, the 200 output will be triggered. In the case that the service responded with any other status code, a Default will be triggered allowing for alternative routing and inspection of the response data.

An Error will be triggered if the flow-node fails to make a request, for example, due to a timeout, or an internal error occurs.

Each output will describe the type of response data and a more complex schema of the expected object structure. In this case, 200 and Default both return a structure containing status, headers, and data. The Error contains message and stack allowing for the error to be identified and tracked.

Authorization

As well as parameters, the OpenAPI specification describes the Authorization requirements of an API. If an OpenAPI client requires authorization, the flow-node will expose that authorization as a parameter to allow you to set the credential to use. For more information on how authorization is defined in OpenAPI, see the documentation for Security requirement objects in OpenAPI 2.0 or OpenAPI 3.0.

The flow-node supports API Key, HTTP Basic, and OAuth 2.0 credentials.

For example, this OpenAPI specification is defining an OAuth 2.0 security definition in the section securityDefinitions which it is named Oauth2. Subsequently, in the method definitions, the Oauth2 security definition is specified as a requirement.

// swagger/gmail.json

...
  "securityDefinitions": {
    "Oauth2": {
      "authorizationUrl": "https://accounts.google.com/o/oauth2/auth",
      "tokenUrl": "https://accounts.google.com/o/oauth2/token",
      "description": "Oauth 2.0 authentication",
      "flow": "accessCode",
      "scopes": {
        "https://mail.google.com/": "Read, send, delete, and manage your email",
        "https://www.googleapis.com/auth/gmail.compose": "Manage drafts and send emails",
        "https://www.googleapis.com/auth/gmail.insert": "Insert mail into your mailbox",
        "https://www.googleapis.com/auth/gmail.labels": "Manage mailbox labels",
        "https://www.googleapis.com/auth/gmail.metadata": "View your email message metadata such as labels and headers, but not the email body",
        "https://www.googleapis.com/auth/gmail.modify": "View and modify but not delete your email",
        "https://www.googleapis.com/auth/gmail.readonly": "View your email messages and settings",
        "https://www.googleapis.com/auth/gmail.send": "Send email on your behalf",
        "https://www.googleapis.com/auth/gmail.settings.basic": "Manage your basic mail settings",
        "https://www.googleapis.com/auth/gmail.settings.sharing": "Manage your sensitive mail settings, including who can manage your mail"
      },
      "type": "oauth2"
    }
  },
...
  "paths": {
...
    "/{userId}/messages/{id}": {
      "get": {
        "operationId": "gmail.users.messages.get",
        "security": [
          { "Oauth2": [ "https://mail.google.com/" ] },
          { "Oauth2": [ "https://www.googleapis.com/auth/gmail.metadata" ] },
          { "Oauth2": [ "https://www.googleapis.com/auth/gmail.modify" ] },
          { "Oauth2": [ "https://www.googleapis.com/auth/gmail.readonly" ] }
        ],
        ...
    },
...
  }
...

The flow-node in API Builder reflects this as an authorization parameter named Oauth2 in the parameters panel:

This parameter can be a Selector, a String, or a Credential. The Selector and String options allow you to get the credential from an external source, for example, the credential could be read from a header on the incoming request or it could be read from some external vault or database. The Credential option tells API Builder to read the credential from its internal credential store.

To simplify populating the credential store with suitable credentials, the plugin will automatically generate stub credentials when loading new OpenAPI specifications. For more information, see Authorization in OpenAPI client. For more information on credentials, see API Builder Credentials.

Configure the OpenAPI client

In some scenarios, you may need to override the information in the OpenAPI specification. For example, to connect to staging servers rather than production ones while in testing.

When a new OpenAPI specification is loaded a default configuration file is created for it in the conf folder of your project.

// conf/gmail.default.js

module.exports = {
    // The configuration settings for the OpenAPI2 flow-node: Gmail
    pluginConfig: {
        '@axway/api-builder-plugin-fn-swagger': {
            'gmail': {
                // It is possible to override URI options when constructing
                // outbound requests to this service.
                uri: {
                    // protocol: 'https',
                    // host: 'hostname',
                    // port: 443,
                    // basePath: '/api'
                }
            }
        }
    },
  // The following authorization credentials needed to use this service.
    // Please follow this guide to manually configure these credentials:
    // https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/api_builder_credentials.html
  authorization: {
    credentials: {
      'Gmail Oauth2': {
        ...
      }
    }
  }
};

Configure endpoint URI

You can configure endpoint URI in the generated configuration file.

Note, this only applies to OpenAPI 2 specifications. For OpenAPI 3 specifications, you can make use of Server parameters defined in the OpenAPI3 specification, or provide a custom Server URL within the flow.

To configure the endpoint URI, set the following parameter:

• uri - If this parameter is set, the plugin module will override the predefined endpoint URI.

Additionally, you can set the port, host, protocol, and base path as described in the following table.

Accept and Content-Type

Starting from version 2.3.0 the OpenAPI client respects the `consumes` and `produces` properties in OpenAPI specifications. It is parsing this information and generates Advanced HTTP Options based on it.

More specifically:

• Accept is created based on the information in “produces”.
• Content-Type is created based on the information in “consumes”. This parameter is only available for methods that have a body or formData payload.

Selecting default mime-type

Here are some rules regarding how the system chooses the mime-type that will be set to Accept and Content-Type headers as part of the underlying HTTP request:

For Accept (always) and for Content-Type where methods have a body payload:

• If there are no valid mime-types in consumes/produces the default mime-type used is application/json (this is for backward compatibility)

• If there is only one type specified in the consumes/produces property it is used by default

• If there are more mime-types the prioritization of selecting the default type is the following order:

  1. application/json
  2. Types ending with +json
  3. The first valid type

For Content-Type where methods have formData parameters:

• If there are no valid mime-types in consumes:
  • If the method has file parameters, the default mime-type is multipart/form-data
  • If the method does not have file type parameters, the default mime-type is application/x-www-form-urlencoded
• If there are valid mime-types in consumes:
  • If there are file type parameters, use multipart/form-data if it exists; otherwise, use application/x-www-form-urlencoded or the first valid type
  • If there are no file type parameters, use application/x-www-form-urlencoded if it exists; otherwise, use multipart/form-data or the first valid type

Overriding the default selection

The system offers the possibility to override the default selection.

If there are types specified in OpenAPI the user can select the desired type from the drop-down:

If there is no consumes/produces information specified in OpenAPI, the system shows an input field rather than a drop-down, and the user can specify the value that they want to use:

Filtering invalid types

According to RFC-7321, the " Internet media types ought to be registered with IANA according to the procedures defined in …" - So, if the OpenAPI specification contains invalid content types, the system will filter those types and will not show them in the UI. A package called content-type is used under the hood to verify the validity of the content type. It does not check if the type is registered in the IANA registry but check about the validity of its name. In other words, a type named ‘application/jsonsssss’ will not be filtered but a type called ‘banana’ will be filtered and not shown in the UI.

Decoding Response

Starting from version 2.3.0 the user has the option to configure the response format. For backward compatibility, by default, the system applies the best effort to decode according to the content types specified. If set to binary Node.js Buffer is returned for further processing in the Flow.

Additional information

For how-to information on accessing Gmail using an OpenAPI client, refer to Access Gmail using OpenAPI client.