This documentation supports the 20.08 version of BMC Helix Platform.  To view an earlier version, select 20.02 from the Product version menu.

Creating a REST API web service request definition

Developers can connect to RESTful services in a codeless way without installing an IDE, writing Java code, or running and managing an integration controller. By creating a web request, you can send or receive files over a REST API call. You must create a one-time RESTful service definition and create web requests for the required methods such as GET, POST, PUT, and so on. This is the first task in the process for connecting to a RESTful service. 

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 of the following formats:
    • .exe
    • .sh
    • .pl
    • .dll
    • .dmg
    • .jar
    • .vbs
    • .js
    • .bat
    • .ksh  
  • To ensure that the REST API URL is not blocked, you must whitelist the URL. For more information, contact BMC Support. 

Before you begin

To ensure 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 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. 

  6. On the 1711_settings_icon.PNGSettings tab, fill out the fields as described in the following table:

    Field

    Description

    Example

    Name

    Type a name for the web request.

    Create Issue

    Request 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 Request Method field.

    None

    (Optional) Add Part Names

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

    Important: The Add 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 Request Method and the Multipart Request toggle key. This happens because in a multipart request, you cannot post a JSON, 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 the check box so that if an error occurs when the web API is run, the process associated with the web API is still run.

    Important: Only when you clear this check box, you can view the web API response metadata fields in a process and use the metadata fields to build process conditions.

    None

    (Optional) Add Headers

    Add the headers for this web request.

    None

    (Optional) Query Parameters

    Add the query parameters for this web request.

    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 values in Path parameter and Query parameter are applied as-is.

    Yes

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

  7. Click Save.

Where to go from here

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