Skip to main content

Getting Started

The Spec API Node is a custom IgniteConnex node that enables seamless integration with OpenAPI specifications. It can dynamically generate HTTP endpoints based on loaded specifications, offering the flexibility to interact with APIs directly from IgniteConnex Editor.

Node Properties​

The Spec API Node can be configured with the following properties:

  • Name: A user-defined name for the node.

  • Endpoint Type: Choose where your API spec lives.

    • IgniteConnex API Spec: Load the API specifications using an IgniteConnex API Key and Spec Resource ID.
      • IgniteConnex API Key: API key required for loading the API Spec.
      • Spec Resource ID: Spec Resource ID required for loading the API Spec.
    • Public URL: Load the OpenAPI specifications from a provided URL.
      • URL: The Public URL of the OpenAPI document.

By selecting the appropriate Endpoint Type and providing the necessary information, you can effectively configure the Spec API Node to load the desired API specifications for your workflow.

Outputs​

The Spec API Node dynamically generates HTTP endpoints based on the loaded OpenAPI specifications. These endpoints correspond to the API operations defined in the specifications. They can be connected to other nodes to create versatile workflows.

Additionally, the Spec API Node allows for routing flows without connecting to other nodes by utilizing the x-entry-node-id parameter defined in the OpenAPI specifications. This parameter can be included in the API paths to route requests to specific nodes within your IgniteConnex Editor. This feature provides a powerful way to control the flow of data and logic directly from the OpenAPI specifications.

We will talk more about how we can route requests using x-entry-node-id in the upcoming sections.

Usage​

Scenario 1: Loading OpenAPI from Public URL​

  1. Begin by dragging and dropping the Spec API Node onto your IgniteConnex Editor. You can access this node from the palette of nodes.

  2. Configure the properties of the node to suit your requirements:

    • Name: Assign a descriptive name to the node instance, helping you easily identify its purpose within your workflow.
    • Endpoint Type: Select the Public URL option. This indicates your intention to load the OpenAPI specifications from a specific URL.
    • URL: Enter the complete URL of the OpenAPI document. This URL points to the location where your OpenAPI specifications are hosted. Ensure that the URL is valid and accessible.

  3. With the properties set, follow these steps to retrieve the OpenAPI specifications from the provided URL:

    • Step 1: Click on the Load Specification button. This initiates the process of fetching the OpenAPI document from the specified URL.

    • Step 2: The node will perform an HTTP request to the provided URL, retrieving the contents of the OpenAPI document.

    • Step 3: Upon successful retrieval, the node dynamically generates HTTP endpoints based on the API operations defined in the specifications.

    • Step 4: These dynamically created endpoints correspond to the various operations defined in the OpenAPI document, including GET, POST, PUT, PATCH, and DELETE.

    • Step 5: Your node is now ready to route incoming HTTP requests to the appropriate endpoints as specified in the API operations.

By following these steps, you have effectively configured the Spec API Node to load OpenAPI specifications from a URL and automatically generate corresponding HTTP endpoints. These endpoints can seamlessly connect to other nodes in your Editor, allowing you to construct intricate and responsive workflows based on the loaded specifications.

Scenario 2: Loading IgniteConnex API Spec with Spec Resource ID and API Key​

  1. Begin by dragging and dropping the Spec API Node onto your IgniteConnex Editor. You can find this node in the palette of available nodes.

  2. Configure the properties of the node to match your requirements:

    • Name: Assign a meaningful name to the node instance, making it easier to identify its purpose within your workflow.
    • Endpoint Type: Choose the IgniteConnex API Spec option. This indicates your intent to load the API specifications using a provided IgniteConnex API key and spec Resource ID.
    • IgniteConnex API Key: Enter the IgniteConnex API key associated with the API specifications you intend to load. You can find this key under the "Clients" tab in your OpenAPI Spec on the IgniteConnex Dashboard.
    • Spec Resource ID: Provide the specific Spec Resource ID corresponding to the API specifications you wish to retrieve. You can also find this ID under the "Clients" tab of your OpenAPI spec in the IgniteConnex Dashboard. Note: The provided IgniteConnex API key and Spec Resource ID are for sample OpenAPI Spec. You can use them to fetch the spec. Example:
    • IgniteConnex API Key: a4504213-bb07-455c-9926-c89aa8646327
    • Spec Resource ID: 2bdec47b4dc156429c105b037aa1a644553b65ec

  3. With the node properties configured, follow these comprehensive steps to fetch the API Spec using the provided IgniteConnex API key and spec Resource ID:

    • Step 1: Click on the Load Specification button. This action initiates the process of fetching the API Spec using the specified IgniteConnex API key and spec Resource ID.

    • Step 2: The node performs an HTTP request to retrieve the API Spec. It sends the provided IgniteConnex API key as a part of the request headers for authentication purposes.

    • Step 3: The request is sent to the specified base URL along with the provided Spec Resource ID.

    • Step 4: If the provided IgniteConnex API key and Spec Resource ID combination is authenticated successfully, the API Spec is retrieved in JSON format.

    • Step 5: The node processes the retrieved API Spec and dynamically generates HTTP endpoints based on the API operations defined in the specifications.

    • Step 6: These dynamically created endpoints correspond to the various operations outlined in the API Spec, such as GET, POST, PUT, PATCH, and DELETE.

    • Step 7: You now have a set of HTTP endpoints ready to route incoming requests based on the operations defined in the API Spec.

By following these detailed steps, you've effectively configured the Spec API Node to fetch the API specifications using an IgniteConnex API key and spec Resource ID. The node dynamically generates corresponding HTTP endpoints based on the fetched specifications. These endpoints can seamlessly integrate into your IgniteConnex flows, allowing you to construct sophisticated workflows aligned with the API operations defined in the loaded specifications.

Routing Requests to Specific Nodes Using x-entry-node-id​

In your OpenAPI specifications, you can leverage the x-entry-node-id field to direct incoming requests to specific nodes within your IgniteConnex Editor. This feature provides you with the capability to route requests dynamically based on the defined path in your API spec.

  1. Within your OpenAPI specifications, identify the specific path for which you want to route requests to a designated node.

  2. Integrate the x-entry-node-id field into that path and indicate the ID of the target node. Here's an example YAML snippet:

    paths:
      /my-custom-path:
        get:
          x-entry-node-id: my-target-node-id
          summary: Fetch data from a specific node
          ...

    In this example, replace my-target-node-id with the actual ID of the node you intend to route requests to.

  3. The x-entry-node-id is the id of the node, It can be found in the info section of the node in the IgniteConnex Editor.

  4. Deploy the updated OpenAPI specifications to the IgniteConnex Dashboard.

  5. Whenever a request is initiated to the /my-custom-path endpoint, the Spec API Node utilizes the x-entry-node-id field to route the request precisely to the node associated with the specified ID (my-target-node-id in this instance).

This advanced feature empowers you to create dynamic and tailored workflows by steering requests towards specific nodes, as defined in your OpenAPI specifications.

Request Validation​

The Spec API Node incorporates robust request validation to ensure that incoming requests align with the defined OpenAPI specification. This validation mechanism safeguards the API's integrity and guarantees that provided data adheres to the anticipated format. The node enforces validation following the OpenAPI specification and the parameters specified for each API endpoint.

Validation Process​

  1. Security Headers Validation: The node validates the existence of mandatory security headers in incoming requests, as stipulated in the OpenAPI specification. If any obligatory security headers are absent, the node responds with a 400 Bad Request status along with an error message indicating the missing headers.

  2. Path Parameters Validation: For each API endpoint, the node verifies the presence of all obligatory path parameters. If any path parameter is lacking, the node returns a 400 Bad Request status accompanied by an error message denoting the absent parameter.

  3. Query Parameters Validation: The node checks for the presence of necessary query parameters in incoming requests. If any requisite query parameter is not provided, the node issues a 400 Bad Request response along with an error message detailing the missing parameter.

  4. Request Body Validation: If the API endpoint mandates a request body, the node confirms whether the body is present and contains valid data. In the event of a missing or invalid request body, the node sends back a 400 Bad Request status coupled with an error message explaining the problem.

  5. x-entry-node-id Validation: The node validates whether the x-entry-node-id field is specified for the requested URL and method in the OpenAPI specification. If this field is absent, the node delivers a 404 Not Found status accompanied by an error message specifying the missing routing information.

Example OpenAPI Specification​

Here's a practical excerpt from an OpenAPI specification that demonstrates the utilization of the x-entry-node-id field for routing requests. It also illustrates the validation of required headers, path parameters, query parameters, and request body:

paths:
  /users/{id}:
    get:
      x-entry-node-id: node-id
      summary: Retrieve user details by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      security:
        - api_key: []

  /products:
    post:
      x-entry-node-id: node-id
      summary: Create a new product
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                price:
                  type: number
              required:
                - name
                - price

Notes​

  • The base URL for fetching API specifications can be customized using the IGNITE_API_BASE_URL environment variable. If not provided, the default base URL https://api.igniteconnex.io will be used.
  • The node UI dynamically updates based on user inputs and loaded specifications, providing a seamless interaction experience.