Overview
This node allows users to interact with any API described by an OpenAPI (Swagger) specification. It dynamically loads the API definition from a provided URL and enables making requests to any endpoint defined in that specification. This flexibility makes it ideal for integrating with APIs that have formal OpenAPI specs without needing custom nodes for each API.
Common scenarios include:
- Accessing third-party REST APIs that provide OpenAPI specs.
- Quickly testing or automating calls to various endpoints of an API.
- Using APIs where the server URL might differ from the one in the spec, allowing overrides.
- Sending custom parameters and request bodies as JSON.
For example, you could use this node to call a weather API endpoint defined in its OpenAPI spec by specifying the operation (HTTP method and path), adding query parameters like location, and receiving structured JSON responses.
Properties
| Name | Meaning |
|---|---|
| OpenAPI Specification URL | URL pointing to the OpenAPI/Swagger specification document describing the API's endpoints, methods, parameters, and schemas. Required to load the API definition. |
| Base API URL | Optional override for the server URL defined in the OpenAPI spec. Useful if the spec lacks a server URL or you want to target a different environment or endpoint. |
| Parameters | A collection of parameters to send with the request. Each parameter has: - Name: The parameter name. - Value: The value to send. - Type: Where to send it (Query, Path, Header, Cookie). |
| Request Body | JSON object representing the request body payload to send with the API call. Can be empty or omitted if not required by the endpoint. |
| Options | Additional options including: - Response Format: Format expected from the API response ( json, string, or binary).- Timeout: Time in milliseconds to wait for the API response before aborting. |
Output
The node outputs an array of items corresponding to each input item processed. Each output item contains:
json: The parsed response data from the API call. This will typically be a JSON object or array matching the API's response schema.- If the response format is set to binary, the node outputs the raw binary data accordingly (e.g., file contents).
Errors during execution are returned as JSON objects with an error field containing the error message, paired with the input item index.
Dependencies
- Requires access to the OpenAPI/Swagger specification URL to load the API definition.
- May require an API authentication token or key depending on the API; credentials can be optionally configured.
- Uses internal helper functions to parse the OpenAPI spec and execute HTTP requests based on it.
- No external environment variables are explicitly required, but network access to the API and spec URLs is necessary.
Troubleshooting
- Invalid OpenAPI URL or Spec Load Failure: If the OpenAPI specification URL is incorrect or unreachable, the node will throw an error indicating failure to load the spec. Verify the URL and network connectivity.
- Invalid JSON in Request Body: If the request body property contains malformed JSON, an error will be thrown. Ensure the JSON syntax is correct.
- Operation Parameter Format Errors: The operation parameter must be a string formatted as
"METHOD:/path"(e.g.,"GET:/users"). Incorrect formats cause errors. - Timeouts: Requests taking longer than the specified timeout will fail. Increase the timeout option if needed.
- Authentication Issues: If the API requires authentication, ensure valid credentials are configured. Missing or invalid credentials may cause authorization errors.
- Parameter Placement: Ensure parameters are correctly assigned to their types (query, path, header, cookie) as per the API spec requirements.
Links and References
- OpenAPI Specification
- Swagger Editor – Useful for validating and exploring OpenAPI specs.
- n8n Documentation – For general guidance on using n8n nodes and credentials.