OpenAPI support in the REST step

  • Release version: Zurich
  • Updated July 31, 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

    The REST step in ServiceNow's Flow Designer now supports importing and using OpenAPI Specifications to configure REST operations efficiently. You can import specifications via URL or by pasting YAML/JSON content. This integration streamlines the configuration of REST steps by automatically populating operations, HTTP methods, parameters, request bodies, paths, and headers based on the specification.

    Show full answer Show less

    Key Features

    • Automatic configuration: Import OpenAPI Specifications to auto-generate inputs and populate REST step fields, ensuring valid requests to OpenAPI services.
    • In-Flow API review: View available API operations directly within the Flow Designer without leaving the interface.
    • Input generation: Required inputs, including complex data types, are created and added to the REST step form and action inputs, mapped appropriately to Workflow Studio data types.
    • Specification management: Imported specifications are stored as records in the sysopenapi table, allowing you to view, delete, or re-import updated specifications.
    • Configurable import size: Default import size limit is 10 MB, adjustable up to 100 MB via system property glide.rest.openapi.maxrequestsize.

    Design Considerations

    • Review and clean parameters: After import, remove unnecessary parameters and headers to avoid sending unwanted data (e.g., select appropriate content-type headers).
    • User-friendly input labels: Ensure inputs have clear, understandable labels to facilitate flow designer use.
    • Remove redundant inputs: Eliminate inputs that do not require configuration by the flow designer, such as those populated by other steps.
    • Avoid changing operations post-configuration: Changing the API operation field resets dependent values and discards unsaved configurations.

    Limitations

    • Request body media types: Only JSON and XML media types are supported. Other media types result in generic string inputs.
    • Partial support for OpenAPI 3.0 components: Some advanced components like oneOf, anyOf, discriminators, callbacks, security schemes, and several others are not supported in the REST step.

    Practical Impact for ServiceNow Customers

    This feature accelerates and simplifies integration with REST APIs defined by OpenAPI Specifications by reducing manual setup and potential errors. Customers can expect more efficient API operation selection and parameter management directly within Flow Designer, improving automation workflows. However, customers should carefully review imported inputs and be aware of current limitations, especially when using advanced OpenAPI 3.0 features or non-JSON/XML request bodies.

    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.