REST API Builder

webMethods.io Integration allows you to trigger project workflows via API endpoints using the REST API Builder feature. You can build custom APIs (or export existing ones), link them with your project workflows, and then make API requests to remotely execute the associated workflows.


How it works

The Rest API Builder feature works at the project level. Meaning, you can create APIs within a specific project and link them to the project workflows only.

To start using the REST API builder feature, navigate to the project of which workflows you want to execute via API endpoints.

Note:

  • All workflows you want to execute via API endpoints must contain both Webhook trigger and Return Data on Sync Webhook action in it.
  • You must Test the Return Data on Sync Webhook action after configuration, otherwise the associated workflow won’t be displayed under the list of available workflows that can be executed via REST APIs.

Let’s understand how to set up and enable REST APIs for your webMethods.io Integration projects with the help of an example.

Let’s say you have a workflow that adds new card to a specific board list in Trello. We will now create an API, which when called, automatically executes this workflow and adds a new card having the specified name to the specified board list in Trello.

Creating a workflow

Let’s first start with creating a workflow for REST API Builder feature.

  1. Add relevant triggers/connectors/actions to canvas

    Add Webhook trigger, Trello connector, and Return Data on Sync Webhook actions to canvas as shown below:

  2. Configure Webhook

    Specify the webhook payload which will be used by the API request at the runtime. Accordingly add relevant keys-value pairs in the Headers, Body and Query fields and then click Next.

    Here, in our example, as we want to pass the name of the card to be created at runtime to the workflow, add a cardname key in the Body field.

    Note: To avoid errors when you test Webhook, ensure you add a value to the cardname key in the Body field.

  3. Configure Trello-Add Card action

    Configure Trello-Add Card action as you would normally do.

    From the left-side panel, locate the Webhook’s Body object and add cardname key in the Card Name field.

    Once this is done, click on Next, optionally Test the action, and click on Done.

  4. Configure Return Data on Sync Webhook action

    Here in our example, we will be sending only card name (which is a string) to the Return Data on Sync Webhook action.

    From the left-side panel, locate the Name key listed under Add Card action response and add in the Response Data field.

    Once this is done, click Next, Test the Return Data on Sync Webhook action and click Done.

    With this, our workflow is configured and ready to be linked with an API request.

Creating an API

To start creating an API, navigate to the project for which you want to create an API and click on APIs tab.

You will be redirected to APIs screen where you will see the list of existing REST APIs (if any) associated with the selected project.

To create a new API, Click Create API. You will be redirected to the Create API configuration window. You can either create a custom API from scratch or simply import an existing API from a swagger file or import an existing API from a swagger URL. As per your requirements, select one method from the options listed below:

  1. Create from scratch
  2. Import API
  3. Import API Using URL
      1. Create a new API from scratch

        1. On selecting this option, you will see the following window. Fill in values for the fields as per the instructions given below:

          • Name - Provide a suitable name for the API you want to create.

          • Description - Provide a short description for this API.

          • Version - Provide a unique version number for this API.

          • Consumes - Select the content type this API can consume. Currently, only application/json is supported..

          • Produces - Select the content type this API will produce. Currently, only application/json is supported.

        2. Once you have entered all the details, click Save.

          The next step is to add desired resources and methods to the created API.

        3. To do so, click the Add Resource button located at the right side of the window.

          This will take you to the Resources and Methods configuration screen. Fill in values for the input fields as per the instructions given below:

          • Path - Specify the resource path you want to expose for this API.

          • HTTP Method - Select an HTTP method to use for the specified resource.

          In our example, since we are adding a new card in Trello, we will select the POST method. You can similarly select GET for get actions, PUT for update actions, DELETE for delete actions, and PATCH to update only specific action fields.

          The next screen that you see will have the specified path and selected HTTP Method. You can optionally provide a short description for this resource and method.

        4. Next, specify/select the workflow you want to execute via this API.

          Note: Only workflows containing webhook and a tested Return Data on Sync Webhook action will be listed in the drop-down field.

          Once you select a workflow, you will see the following screen:

          Parameters - The webhook payload keys-along with their source (Header/Body/Query)-that are associated with the selected workflow, are listed under the Parameters section. You can optionally add description for these keys in the Description field.

          Responses - Enter the response status for a failed API call. You can optionally add more response statuses by clicking the Add Response button.

        5. Once you have entered the details, click Done. This will take you back to the Resources and Methods screen.

        6. Next, click on Save. With this, you have successfully created an API.

        7. Note: You can select more than one HTTP method for a resource path in an API.

          For example, let’s say we want to use the same resource path /sample for POST and GET HTTP methods. To do so, simply repeat the above process twice for POST and GET methods.

      2. Import API

        1. Select this option, click on Browse, import a swagger file, and click Next.

        2. Fill in values for the input fields as per the instructions given below:

          • Name - Provide a suitable name for the API you want to create.

          • Version - Provide a unique version number for this API.

        3. Once this is done, click Save.

      3. With this, you have successfully imported and saved an existing API for your project.

      4. Import API Using URL

        1. Select this option and click Next.

        2. In the Basic Info page, complete the following fields as per the instructions given below:

          • Name - Provide a suitable name for the API you want to create.

          • Swagger URL - Enter the URL for the Swagger document.
            The URL should begin with https://. The swagger documents must be in either JSON format with a .json file extension or YAML.

          • User Name - Provide a user name to authorize access to your swagger definition.

          • Password - Provide a password to authorize access to your swagger definition.

          Note: Provide Username and Password fields only if swagger API needs authentication, else it can be left blank too.

          Once you have entered all the details, click Save.

      5. With this, you have successfully imported and saved an existing API for your project.

Executing workflows via API calls

Note: To execute workflows via API requests, you will have to use an external service that is capable of sending HTTP requests. In our example, we will use Postman.

Let’s now understand how to make API requests and execute workflows.

  1. Set relevant HTTP method in Postman

    Set the HTTP method depending on the workflow you want to execute, in Postman.

  2. Navigate to API Details screen of your API

    From the API Details window, copy the API endpoint.

    Now, paste the same in the Request URL field in Postman.

  3. Append the specified Resource and Method to the copied API endpoint

    Click on Resources and Methods tab located in the left-side panel. You will see a list of resources and methods associated with the created API. Copy the required resource and method.

    Now, append the same to the API endpoint added in the Request URL field in Postman.

  4. Configure the settings required to make this API request in Postman

    Authorization - For Postman to send this HTTP request, you will first have to enter your Username and Password associated with your webMethods.io Integration tenant. To do this, click on the Authorization tab, set Type to Basic Auth, and add your credentials in the Username and Password fields.

    Next, add relevant headers associated with this API request. To do this, click on the Headers tab, and set Content-Type to application/json. Add rest of the headers as key-value pairs depending on your requirements.

    Note: Currently the REST API builder only supports the application/json content type and basic authentication.

    Body - Enter the data you want to send in the body of the API request in the JSON format. To do so, click the Body tab and select ‘raw’ format.

    In our example, since we need to pass the name of the card to be created, we will pass card name in the API request body. Please ensure that the payload keys being sent in the request body match the webhook payload keys added earlier.

    Note: HTTP methods - GET will fetch data and DELETE will delete the specified resource. Hence, the Body field for these methods will remain blank. On the other hand, HTTP method - POST, PUT, PATCH will make certain modifications in the specified resource and hence, mandatorily require values in the Body field.

  5. Send API request

    Once you have configured the required settings in the Postman app, hit the Send button to send your API request.

    This will trigger the workflow associated with the API request and on successful execution, you will see the output of the workflow in Postman interface:

    In our example, when you check the specified Trello list, you will see that the specified card is added to the Trello list.

Managing APIs

You can edit and delete the existing APIs through the APIs tab.

Editing an API

When you click on the APIs tab, you will see the list of existing APIs of your project. Locate the API you want to modify and click the Edit icon given against it.

This will redirect you to the API Details tab, where you can view the existing API details.

To modify the relevant details, click on the Edit icon located beside the Basic Info label.

Next, click on the Resources and Methods tab and then click the Edit icon given against the relevant resource you want to modify.

Note: You can only edit the resources and methods of an API manually if it has been created from scratch.
If you have imported an API through a Swagger file or URL, you will need to upload the modified swagger file or provide the URL for the updated file to make relevant resource and method changes.

Deleting an API

To delete an API, click on the Delete icon given against the API name and confirm the delete action in the dialog box that appears.

This will delete the API permanently from your webMethods.io Integration tenant.