Thank you for your feedback.
Form temporarily unavailable. Please try again or contact docfeedback@servicenow.com to submit your comments.

OpenAPI support in the REST step

Log in to subscribe to topics and get notified when content changes.

OpenAPI support in the REST step

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 Flow Designer 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. You must remove one 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.

Feedback