# OpenAPI

The OpenAPI connector is a universal connector that can be used to work with any application that describes its API endpoints using the OpenAPI specification.

Note: We recommend using the connector with RESTful APIs (opens new window) for the best experience. Refer to the Limitations section for more info.


# Basics

# What is OpenAPI?

OpenAPI is a specification that acts as a machine-readable interface for describing, producing, consuming, and visualizing RESTful web services.

An OpenAPI document, also called a Swagger file, can be used to fulfill a variety of purposes:

  • Generate API documentation
  • Generate servers and clients in various programming languages
  • Automate test case generation
  • ... and more!

Check out OpenAPI's resources to learn more (opens new window).

# What's a Swagger file?

A Swagger file describes the endpoints available in an API and includes the following data:

  • Endpoint method
  • Endpoint path
  • Headers
  • Parameters and query strings
  • Request and response schemas

For example: This portion of a sample Swagger file (opens new window) describes a POST /pet endpoint:

paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      operationId: addPet
      requestBody:
        $ref: https://api.swaggerhub.com/domains/Colon-Org/PetStore-Objects/1.0#/components/requestBodies/PetRequest
      responses:
        '405':
          description: Invalid input
      security:
        - petstore_auth:
            - 'write:pets'
            - 'read:pets'

# What can I do with the OpenAPI connector?

The OpenAPI connector parses a user-provided Swagger file and uses its contents to generate a user interface - including actions, input and output fields, objects, and so on - in Workato. Note, however, that the quality of the connector depends on the contents of the Swagger file.

If you need to customize the interface, you can use the OpenAPI connector as a template to build custom connectors. For example: If your connector requires custom icons or authentication, use the OpenAPI connector as a starting point and customize it as needed.

# When should I use the OpenAPI connector?

Consider using the OpenAPI connector if:

1

There isn't an app-specific connector available, AND

2

The application provides a Swagger file, AND

3

The API described in the Swagger file follows REST standards (opens new window)

The following diagram illustrates when to consider using the OpenAPI connector and when to use other connectors or even build custom connectors:

Highlighted object picker field in the Workato UI

# How do I use the OpenAPI connector to create custom connectors?

While the OpenAPI connector is a quick, easy way to connect to applications, there might be times you want to create a custom connector for a specific application.

For example, you might want to:

  • Improve the UX by using the applications's name and icon
  • Simplify the connection settings
  • Implement custom authentication flows

Check out the Using the OpenAPI connector to create custom connectors guide to get started.

Note: Customizing the connector's code can make upgrading to a new version more complex. Refer to the Upgrading an OpenAPI connector's source code guide for more info.


# Supported Features

# Swagger Versions And Formats

The OpenAPI connector supports the following Swagger versions and formats:

The Swagger file you provide must be valid YAML or JSON and conform to the specifications for either supported version.

# Authentication Methods

The OpenAPI connector supports the following authentication methods:

  • None
  • Basic
  • Header
  • Query params
  • OAuth 2.0: Authorization code grant
  • OAuth 2.0: Client credentials grant
  • OAuth 2.0: Resource owner password grant

Learn more in the OpenAPI connector authentication guide.

# Interface Customization

The OpenAPI connector automatically generates the user interface based on the content of the provided Swagger file. The following elements can be customized to improve user experience:

  • Object names and hints
  • Field names and hints
  • Links to external documentation
  • API operation grouping
  • Fields to ignore

Check out the Customizing OpenAPI user interfaces guide for more info and examples.


# Actions

The OpenAPI connector supports the following actions:

  • Create record
  • Update record
  • Search records
  • Get record details by ID
  • Execute operation
  • Delete record
  • Custom action

When the OpenAPI connector parses the provided Swagger file, API operations are assigned to one of the supported actions listed above. For example: An endpoint that creates a new pet record would be assigned to the Create record action.

Check out the Customizing OpenAPI user interfaces guide for more info and examples.


# Limitations

When using the OpenAPI connector, keep in mind that:

  • The quality of the connector is dependent upon the Swagger file's contents. The user interface in the Recipe Editor is created from the contents of the Swagger file. For example: If the Swagger file doesn't contain descriptions of API operations or request/response fields, the experience for end users will be less than ideal.

  • The connector is built for use with RESTful APIs. We recommend using the connector with RESTful APIs (opens new window) for the best experience. While non-REST APIs may be used, issues with grouping API operations into actions may arise.


# Setup

Ready to get started with the OpenAPI connector? Check out these guides:


Last updated: 11/12/2022, 10:59:23 AM