OpenAPI support in the REST step

  • Release version: Yokohama
  • Updated January 30, 2025
  • 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 within ServiceNow's Flow Designer enables customers to import OpenAPI Specifications (YAML or JSON) directly by URL or content paste. This integration streamlines the configuration of REST step operations by automatically populating HTTP methods, parameters, request bodies, paths, and headers based on the imported specification. It allows flow designers to review and select API operations without leaving the Flow Designer interface, ensuring accurate and efficient setup of REST requests.

    Show full answer Show less

    Key Features

    • Automatic Input Generation: Required inputs from the OpenAPI Specification are created and mapped to Workflow Studio data types (including complex data objects) and added to the REST step form for use at runtime.
    • Specification Size Management: Supports importing OpenAPI Specifications up to 10 MB by default, with a configurable maximum of 100 MB via the glide.rest.openapi.maxrequestsize system property.
    • Specification Management: Imported specifications are stored as records in the sysopenapi table for viewing or deletion. To update a specification, it must be deleted and re-imported.
    • Review and Customization: After import, parameters and headers can be reviewed and unnecessary ones removed. Input labels should be made user-friendly to aid flow designers, and inputs not requiring configuration can be removed to simplify the interface.

    Design Considerations

    • Review all imported parameters and headers; remove those not needed to avoid sending unintended data.
    • Ensure input labels are clear for easy understanding and configuration by flow designers.
    • Do not change the API operation after configuring values, as this resets dependent configurations.
    • Remove inputs that are automatically populated from other steps to prevent redundant configuration.

    Limitations

    • Request Body Media Types: Only JSON and XML media types are supported in the request body. Unsupported media types default to a string input.
    • Partial OpenAPI 3.0 Support: Some OpenAPI 3.0 components are not supported, including advanced schema properties (oneOf, anyOf), discriminators, callback objects, security schemes, tags, external documentation, server objects, and recursive references.

    Practical Impact for ServiceNow Customers

    This feature allows customers to rapidly integrate and configure REST API calls in Flow Designer using industry-standard OpenAPI Specifications. It reduces manual configuration errors and improves efficiency by leveraging existing API documentation. Customers should carefully review and customize imported inputs to ensure their flows interact correctly with external APIs and be mindful of current limitations regarding media types and OpenAPI 3.0 components.

    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.