OpenAPI support in the REST step

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of OpenAPI support in the REST step

    OpenAPI support in the REST step enables ServiceNow customers to configure REST operations easily by importing OpenAPI Specifications directly into Flow Designer. Specifications can be imported via URL or by pasting YAML or JSON content, allowing users to populate REST step fields and action inputs with detailed API information. This integration helps streamline the setup of REST requests by automatically generating required inputs aligned with the API’s definitions.

    Show full answer Show less

    Key Features

    • Automatic Configuration: Importing an OpenAPI Specification auto-fills REST step operations, HTTP methods, parameters, request bodies, paths, and headers.
    • Input Generation: The system creates inputs based on the API requirements (e.g., parameters like "name") and maps OpenAPI data types to Workflow Studio data types, supporting complex objects where needed.
    • Specification Management: Imported specifications are stored in the sysopenapi table for viewing or deletion. To update a spec, delete and re-import it.
    • Import Size Limits: By default, up to 10 MB specifications can be imported; this limit can be increased to 100 MB via system properties.

    Design Considerations

    • Parameter Cleanup: Review and remove unnecessary parameters and headers added from the specification to avoid sending unwanted data.
    • User-Friendly Inputs: Ensure input labels are clear for flow designers and remove inputs that do not require configuration to simplify action usage.
    • Operation Stability: Avoid changing the API operation after configuration, as this resets dependent values and discards unsaved settings.

    Limitations

    • Request Body Media Types: Only JSON and XML media types are supported. Other media types default to a generic string input.
    • Partial OpenAPI 3.0 Component Support: Certain OpenAPI 3.0 components such as oneOf, anyOf, Discriminator, Callback, Security Scheme, Tag, Server, and others are not supported in the REST step.
    • Specification Features Not Supported: Recursive references and some specification extensions cannot be processed.

    Practical Impact for ServiceNow Customers

    This capability allows customers to integrate external APIs more efficiently within their flows by leveraging existing OpenAPI Specifications. Users can rapidly configure REST steps with accurate inputs and operations, reducing manual setup and errors. However, customers should carefully review imported parameters and understand the limitations around media types and OpenAPI 3.0 feature support to ensure their integrations function as intended.

    Populate REST step fields and action inputs with information imported from an OpenAPI Specification. Import specifications by providing a URL to the YAML or JSON, or copying and pasting content.

    Benefits

    OpenAPI support in the REST step offers these benefits.

    • Use information imported from an OpenAPI Specification to configure REST step operations, HTTP methods, parameters, request body, path, and headers.
    • Review available API operations without leaving the Flow Designer interface.
    • Generate inputs required for the REST step to send valid requests to an OpenAPI service and add them to the REST step in the correct location.
    Note:
    Always review REST step values imported from an OpenAPI Specification before sending a request. Remove parameters, headers, and inputs that the API does not require.

    Generated inputs

    When you import an OpenAPI Specification, the system creates any required inputs and adds them to the REST step form where appropriate. At runtime, the system sends a REST request that contains input values provided to the action. For example, if an API requires a name parameter passed in the request, the system creates a name input and adds it to the REST step. When you add the action to the flow, name becomes an input to the action.

    The system maps OpenAPI data types to Workflow Studio data types. For example, if the OpenAPI Specification requires a user object, then the system creates a complex data object as input. For more information, see Complex data.

    Specification size limit

    By default, the system can import OpenAPI Specifications up to 10 MB. To increase the import size, update the glide.rest.openapi.max_request_size system property. The maximum value is 100 MB.

    Specification management

    Import an OpenAPI Specification by selecting options in the REST step. For more information, see REST step. Importing an OpenAPI Specification creates a record in the OpenAPIs [sys_openapi] table. You can view or delete specification records directly from this table. To update a specification, delete it and import it again.

    Design considerations

    Create a REST step from an OpenAPI Specification with these considerations in mind.

    Remove unnecessary REST step parameters
    When importing an OpenAPI Specification, the system adds all parameters and headers present in the specification to the REST step. Review the final REST step values and remove parameters you do not want to send in the request. For example, if the API accepts content type headers for both JSON and XML, the system adds both headers to the REST step. Remove one of the headers depending on the content type you want to receive in the response.
    Make input labels user-friendly
    Ensure that input labels required for the REST step are clear and understandable. Clear labels enable flow designers to easily understand the required inputs when using the action in a flow.
    Remove inputs that do not require flow designer configuration
    When importing an OpenAPI Specification, the system adds all inputs present in the specification to the action input section. Remove any inputs that do not require a flow designer to configure. For example, if a REST step variable receives a value from another step in the action, an action input is not required.
    Avoid changing the API operation
    Changing the value of the API Operation field removes all values dependent on that operation. If you configure the OpenAPI Specification values in the REST step form, then change the operation, the system does not save your configuration. Values that are entered manually by a user are not affected.

    Limitations

    Create a REST step from an OpenAPI Specification with these limitations.

    Request body media types
    The request body only supports JSON and XML-based media types. If the selected operation from the imported OpenAPI Specification contains a request body with a different media type, the system adds a data pill of type String to the Request body field.
    OpenAPI 3.0 components

    OpenAPI 3.0 adds new components to Swagger 2.0 to describe an API in further detail. OpenAPI support in the REST step supports some, but not all of these components. The REST step does not currently support these components.

    • Schema Object: oneOf, anyOf properties
    • Discriminator Object
    • Info object: termsOfService, contact, license fields
    • Example Object
    • Link Object
    • Callback Object
    • Security Scheme Object
    • Security Requirements Object
    • Tag Object
    • External Documentation Object
    • Server Object
    • Specification extensions
    • Recursive references

    More information on these components is available in the OpenAPI documentation. See OpenAPI Specification.