REST APIs

How REST API 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 Workflows or Flow services in that project.

To start using the REST API builder feature, navigate to the project of which Workflows or Flow services you want to run using API endpoints.

Example - Setup and Enable REST APIs for Projects

Assume that you have a Workflow that adds new card to a specific board list in Trello. To create an API, which when called, automatically runs the Workflow and adds a new card having the specified name to the specified board list in Trello.

Solution

It consists of three steps:

1. Creating a Workflow

2. Creating an API

3. Running Workflow through API Calls

Creating a Workflow

1. Add relevant triggers/connectors/actions to canvas, that is, add Webhook trigger, Trello connector, and Return Data on Sync Webhook actions to canvas as follows:

   

2. Configure Webhook

   a. Specify the webhook payload that is 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.

   In this example, the name of the card to be created is sent 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

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

   

   b. Click Next, optionally Test the action, and click on Done.

4. Configure Return Data on Sync Webhook action In this example, only card name (which is a string) is sent to the Return Data on Sync Webhook action.

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

   

   b. Click Next.

   c. 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

1. Navigate to the project for which you want to create an API and click on APIs tab. You are redirected to APIs page where the list of existing REST APIs (if any) associated with the selected project appear.

   

2. Click Create API. You are redirected to the New API page. 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 following options:

   • Create from scratch

   • Import API

   • Import API Using URL

   

Create a new API from scratch

1. Enter the following details:

   • 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.

   • Access - You can mark the API as Public or Private by selecting this option. When you create a new API from scratch, this option is set to Public by default.
     

     

     When you mark the API as Public, the API details page shows the API endpoints as two distinct URLs:
     
     Public URL: A public endpoint is accessible externally via the Internet. You can view and copy the URL details using the icons alongside or from the JSON and YAML files under the Documentation field.
     Internal URL: An internal endpoint is accessible only from webMethods network. You can view and copy the URL details using the icons alongside or from the JSON and YAML files under the Documentation field.

     

     When you mark the API as Private, the API details page shows the API endpoints as two distinct URLs:
     
     Private URL: A private endpoint is used when a private network is configured. Access is limited exclusively to your private network, preventing any outside access, including from your webMethods network or webMethods applications within your tenant. You can view and copy the URL details using the icons alongside or from the JSON and YAML files under the Documentation field.
     Internal URL: An internal endpoint is accessible only from webMethods network. You can view and copy the URL details using the icons alongside or from the JSON and YAML files under the Documentation field.

     Note

     • To enable the execution of an API from the IBM webMethods API Gateway, you can use the Internal URL under the API Endpoints, which is displayed on the Rest API page.
       For more information, see the FAQs section: How to invoke a REST API using the Internal URL in webMethods API Gateway?
       

     • Support for domains with -internal will soon be deprecated, so you must reconfigure the alias in IBM webMethods API Gateway by using the Internal URL provided under API Endpoints on the REST or SOAP API details page.
       

     • In an existing API, when you change the selected value for the Access field from Private to Public or Public to Private, the changes may take a while to propagate for the ongoing API executions.

   • 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. Click Save. The next step is to add desired resources and methods to the created API.

3. Click the Add Resource button located at the right side of the page.

   

   You are redirected to the Resources and Methods configuration page.

4. Enter the following details:

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

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

   

5. Select the POST method as in this example a new card is added in Trello. You can similarly select GET for get actions, PUT for update actions, DELETE for delete actions, and PATCH to update only specific action fields.

6. Select the HTTP method to specify the path. You can optionally provide a short description for this resource and method.

7. Select the Workflow you want to run through this API.

   Note

   • Only workflows containing webhook and a tested Return Data on Sync Webhook action is listed in the drop-down field.
   • You can also select the Flow service instead of Workflow too. This example describes steps using a Workflow.
     

   

   After you select a workflow, the following fields appear:

   

8. Enter the following details:

   • 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.

     Note

     • For Workflows, if the path URL has parameters in the format, /postdata/{n1}/{n2}, the values of n1 and n2 are derived from the Workflow parameters.
       

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

   

9. Click Done. The Resources and Methods page appears.

10. Click Save. With this, you have successfully created an API.

    

Note

You can select more than one HTTP method for a resource path in an API. For example, 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.

Import API

1. Select Import API/I have an existing API.

2. Click Browse and import a swagger file.

   

3. Click Next. The Basic Info page appears.

4. Enter the following details:

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

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

   • Convert to Defined Type – Select the value as true or false.

   

   Note

   • The default selection for Convert to Defined Type field is true, and this field is only available when creating a REST API using the Import API/I have an existing API option and using a swagger file.
     If the value for Convert to Defined Type field is selected as True, it indicates that the input variables in the request body are converted to the datatype defined in the signature. However, if the value is set to False, the input variables in the request body are passed as-is in the service pipeline.
   • You have the option to edit the Convert to Defined Type field value using the edit option. However to save these changes it is important to re-upload the document.

   

5. Click Save.

   

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

Import API Using URL

1. Select Import API using URL.

   

2. Click Next. The Basic Info page appears.

3. Enter the following details:

   • 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.
     

   • Convert to Defined Type – Select the value as true or false. Once the value is selected, Convert to Defined Type field is visible in the API details page and is editable.

     Note

     • The default selection for Convert to Defined Type field is true, and this field is only available when creating a REST API using the Import API Using URL option and using a swagger file.
       If the value for Convert to Defined Type field is selected as True, it indicates that the input variables in the request body are converted to the datatype defined in the signature. However, if the value is set to False, the input variables in the request body are passed as-is in the service pipeline.
     • You have the option to edit the Convert to Defined Type field value using the edit option. However to save these changes it is important to re-upload the document.
     • Provide the Username and Password only if the swagger API needs authentication, else it can be left blank.
       

4. Click Save.

   

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

Running Workflows through API calls

1. Set relevant HTTP method in Postman Set the HTTP method depending on the Workflow you want to run Postman.

   

2. Navigate to the API Details page of your API

   a. From the API Details page, copy the API endpoint.

   

   b. Paste the same in the Request URL field in Postman.

   

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

   a. Click the Resources and Methods tab located in the left-side panel. A list of resources and methods associated with the created API appear.

   b. Copy the required resource and method.

   

   c. 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

   a. Authorization - For Postman to send this HTTP request, you must first enter your Username and Password associated with your 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.

   

   b. 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.

   

   c. 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 this example, the name of the card to be created is sent in the API request body. Ensure that the payload keys being sent in the request body match the webhook payload keys added earlier.

   

   Note

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

5. Send API request

   a. Click the Send button to send your API request after you provided all details. The Workflow associated with the API request is invoked and on successful run, you can view the output of the Workflow in Postman interface:

   

   Note

   Whenever a Workflow is invoked from the REST API, the Path parameter provided in the REST API URL is included to the body of the request, as there is no Path paramater option in Workflow.

   In this example, when you check the specified Trello list, you can observe 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 REST APIs

1. Go to the APIs tab. The list of existing APIs of your project appear.

2. Locate the API you want to modify and click the Edit icon given against it.

   

   You are redirected to the API Details tab, where you can view the existing API details.

3. Click 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 must upload the modified swagger file or provide the URL for the updated file to make relevant resource and method changes.
     

Deleting REST APIs

1. Go to the APIs tab. The list of existing APIs of your project appear.

2. Locate the API you want to delete and click the Delete icon given against the API name.

3. Confirm the delete action in the dialog box that appears.

   

The API is deleted permanently from your Integration tenant.

Copying REST APIs

To copy an existing REST API to another project,

1. Go to the APIs tab. The list of existing APIs of your project appear.

2. Locate the API you want to copy to another project and click the Copy icon given against the API name.

   

   The Copy dialog box appears.

   

3. Enter the following details.

   • Select Project: Choose the project where you want to copy the API.
   • Name: Provide a new name for the copied API.
     

4. Click Save.

   

The system creates a copy of the REST API with the new name, and it appears in the REST APIs page of the target project.