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

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  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 Settings 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