Creating a REST API web service request definition

Administrators can connect to RESTful services in a codeless way without installing an integrated development environment (IDE), writing Java code, or running and managing an integration controller. You can send or receive files over a REST API call by creating a web request. To connect to a RESTful service, you must first create a one-time RESTful service definition and then create web requests for the required methods, such as GET, POST, PUT, and so on. 

For example, if you want to connect to a JIRA RESTful service, you must create a one-time service definition for the JIRA REST API and create web requests, such as Create JIRA issue (with PUT method) or Assign JIRA issue (with POST method). 

Important

  • You cannot upload or download attachments with the following extensions:
    • .exe
    • .sh
    • .pl
    • .dll
    • .dmg
    • .jar
    • .vbs
    • .js
    • .bat
    • .ksh  
  • Make sure to add the REST API URL in the allowlist, so the firewall does not block it. Contact BMC Support for more information.

Related topics

Configuring-the-authentication-credentials-of-REST-API-web-services

Mapping-the-REST-API-web-service-request-alias-to-an-appropriate-connection

Before you begin

To make sure that the REST API request body (for PUT and POST methods) and the response (for GET method) is provided, you must create a document definition. For more information, see Defining-a-document-schema.

To create a web service request definition

  1. Log in to BMC Helix Innovation Studio. 
  2. On the Workspace tab, select the application from which you want to connect to a RESTful service. 
  3. Click the Web APIs tab, and click New.
  4. On the Properties 22_1_General properties icon.JPG tab, provide a name for the RESTful service, such as JIRA API.
  5. On the New web API page, perform one of the following steps:
    • To add a web request to an existing Web API, click the Web API name. 
    • To create a new Web API, click New request. 

  6. On the Settings 22_1_settings_icon.PNGtab, fill out the fields as described in the following table:

    Field

    Description

    Example

    Name

    Type a name for the web request.

    Create Issue

    Method

    Select the HTTP method of the web request.

    POST

    (Optional) Multipart request

    If you want a request to be of the multipart type, then select this toggle key.

    Important: The Multipart request toggle key is displayed only when you select Post and Put in the Method field.

    None

    (Optional) Part names

    Click this option to enter the key as given in the REST API.

    Important: The Part names field is displayed only when you select the Multipart request toggle key.

    Attach1

    Path

    Specify the URL path on which the method is invoked.
    Format of the URL: /rest/api/

    /rest/api/latest/issue/{issueid}

    (Optional) Body

    From the list, select the Document Definition that you created earlier from which you want to copy the body in JSON format.

    Typically, this is needed for the POST or PUT methods, but might not be required for other methods.
    Important: The Body field is not displayed if you have selected Post or Put as Method and the Multipart request toggle key; because you cannot post a JSON in multipart request, but you can post other content types, for example, .zip and .jpeg.

    None

    (Optional) Response

    From the list, select the Document Definition that you created earlier from which you want to copy the response in JSON format.

    Important: If the content type of the Response field is other than JSON, the response is returned as an attachment. While designing a process, you can map the Response field with the attachment.

    None

    Error on unsuccessful response

    Clear this check box to keep the process associated with a web API running even if there is an error with the web API.

    Important: You must clear this check box to view the web API response metadata fields in a process and use the metadata fields to build process conditions. For more information, see Configuring-web-requests-in-a-business-process.

    None

    Encode request parameters

    Select the toggle button to encode the following parameters:

    • Path parameter and its value
    • Query parameter and its value

    Important:

    • You cannot choose the parameters or values that you want to encode.
    • If you do not encode the parameters, the values in the Path and Query parameters are applied as is.

    Yes

    Header names

    (Optional) Add 

    Add the headers for this web request.

    None

    Query parameter names

    (Optional) Add

    Add the query parameters for this web request.

    None

    If you have added the path parameters in the Path field, the parameters are populated automatically in the Path Parameters field.

  7. Click Save.

To copy a web request definition

You can reuse an existing web request definition by copying it within the application or to a different application or library.

  1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.
  2. Select the application or library from which you want to copy a RESTful service.
  3. Click Web APIs and select the web request definition that you want to copy, and then click Copy.

  4. In the Copy definition dialog box, enter the following details:

    • From Target application/library, select the target application or library where you want to copy the web request.
    • In the Definition name field, type a name for the web request definition. 

    22_1_Copy record definition.png

    The copied web request is saved in the target application.

Where to go from here

To configure the authentication credentials of Rest API web services, see Configuring-the-authentication-credentials-of-REST-API-web-services

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*