Integration Cloud 7.0.0 | Applications | REST Applications | Creating and updating REST Applications
 
Creating and updating REST Applications
These screens allow you to define a REST Application, define Resources and Actions, and then create a REST Application. See REST Applications for conceptual information on REST Resources, HTTP Methods, HTTP Status Codes, HTTP Headers, and Parameters.
*To create a REST Application
1. From the Integration Cloud navigation bar, click Projects > <Select a Project> > Applications > REST Applications > Add New Application.
2. In the Define Application Details page, complete the following fields. Required fields are marked with an asterisk on the screen.
Field
Description
Name
Type a name for the REST Application.
Description
Type an optional description for the REST Application. The description you enter here will appear in the Applications page.
Default Endpoint URL
Specify the Endpoint for the Application. It is the login endpoint URL to initiate communication with the SaaS provider. To get the end point, see the back end documentation available on the internet for the SaaS provider.
Authentication Type
Every back end provides its own authentication mechanism. Get the authentication details from the back end documentation and select the supported Authentication Type from the drop-down list.
Application Icon
Click Browse and select another icon for the REST Application, if necessary.
3. Click Next.
The Define Resources and Actions page appears.
4. In the Define Resources and Actions page, click Add Resource to create a new REST Resource.
The Add Resource dialog box appears. In the Add Resource dialog box, complete the following fields:
Field
Description
Name
Type the Resource name.
Path
Type the path to the Resource. The Resource path is relative to the endpoint specified. Each REST Resource derives its path from the namespace of the REST Resource. For example, if the REST Resource is named myREST.myRESTResource, the path is “/myREST.myRESTResource”.
You can define dynamic parameters in the resource path by enclosing each parameter within { } brackets. For example, to get the employee data corresponding to a dynamic parameter called employeeID, specify the resource path as /employee/{employeeID}. To get item information from a particular department in a store, specify the resource path as /store/{departmentID}/{itemID}.
Note:
While adding an Action, if your Resource path contains { } brackets, for example, /user/{userID}, you must add a request parameter having the same name, that is, "userID", and set the Parameter Type to URI_CONTEXT.
5. Click Add to create the Resource. You can Edit or Delete the Resource from the Define Resources and Actions page.
6. In the Define Resources and Actions page, select the Resource and click Add Action.
Note:
Every Resource must have an Action associated with it.
In the Add Action to Resource dialog box, complete the following fields:
Field
Description
Method
Select an HTTP Method.
*GET - Reads or retrieves a representation of a resource. For example, GET <endpointurl>/addresses/2 will retrieve an address with an ID of 2.
*PUT - Updates an existing resource. For example, PUT <endpointurl>/addresses/3 will modify the address with an ID of 3.
*POST - Creates a resource. For example, POST <endpointurl>/addresses will create a new address.
*DELETE - Deletes a resource identified by an URI. For example, DELETE <endpointurl>/addresses/4 will delete an address with an ID of 4.
Description
Type an optional description for the Action.
Request Parameter
You can set parameters that become part of the outgoing request. Parameters specify the variable parts of your resources. Click Add Parameter to add a parameter to the request. Complete the following fields:
Name - Type the parameter name.
Value - Type a value for the parameter.
Parameter Type - Select the parameter's type, which determines how the parameter should be used.
f you select an AWS authentication type, then you must add a mandatory request parameter in all the Actions you create. The parameter name must be aws.service and the parameter type must be CFG_PARAM. Type the service name in the endpoint URL as the parameter value. For example, if the endpoint URL is https://<instance>.s3.com/, type the parameter value as s3.
REST services rely on HTTP methods (GET, POST, PUT, and DELETE) to make requests to a SaaS provider. Thus the parameters are closely tied to these HTTP methods, as they are sent as part of these HTTP method requests. The parameters are part of the HTTP URI. CFG_PARAM is an internal configuration parameter.
URI_CONTEXT parameters are passed as the path component of a REST Resource URI, and the parameter names correspond to the URI path variable names specified in the {} annotation. For example, if the URI is https://api.twitter.com/1.1/users/{id}, the Resource path will be /users/{id}, the parameter type will be uriContext, the parameter name will be id, and the value could be the user id, for example, either 1, or 2, or 3.
QUERYSTRING_PARAM parameters are passed as the query component of a REST resource invocation request. For example, if the URI is https://api.twitter.com/
1.1/users/show.json?screen_name=twitterdev, the resource path will be /users/show.json, screen_name is the name of the parameter, twitterdev is the value of the parameter, and the parameter type is query.
FORM_ENCODED_PARAM - Define a parameter of type FORM_ENCODED_PARAM if you want to send the parameter as part of the Request body. FORM_ENCODED_PARAM allows you to send simple key value parameters embedded in the Request body for POST or PUT requests. This uses the default web form encoding, which is application/x-www-form-urlencoded.
Note:
For passing parameters of FORM_ENCODED_PARAM type, you will not be able to define the Request body for a Resource, as the generated parameter key value string will be automatically embedded in the Request body.
Required - Select this option if you want this parameter to be made mandatory while creating an Integration.
Request Header
HTTP headers allow the client and the server to pass additional information with the request or the response.
Note:
Do not add an authorization header if you use credentials as the mode of authentication.
Click Add Header to add a request HTTP header. In the Add Header dialog box, complete the following fields:
Name - Type the Header name.
Value - Type a value for the Header.
Required - Select this option if you want this Header to be made mandatory while creating an Integration.
Request Body
In the Request Body pane, complete the following fields:
Content Type If the documentation of the SaaS provider specifies that the content type of the request body is JSON, select application/json as the content type. If the documentation of the SaaS provider specifies that the content type of the request body is XML, select application/xml as the content type. If the documentation of the SaaS provider specifies that the content type of the request body is binary, select Binary as the content type. These options allow you to control the content in an HTTP request body.
Document Type - Select a Document Type for the request body or click Create Document Type to create a new Document Type. See Creating Document Types from Scratch.
Note:
Document Types created for a REST Application do not appear in the Develop > Document Types screen but appears only in the Document Types panel for the selected REST Application.
If the request payload is an array of object, then first create a document type resembling the content of the object, and then select the Array option.
Response Header
In the Response Header pane, click Add Header to add a Response HTTP header.
Note:
Do not add an authorization header if you use credentials as the mode of authentication.
Complete the following fields:
Name - Type the Header name.
Value - Type a value for the Header.
Required - Select this option if you want this Header to be made mandatory while creating an Integration.
Response Body
In the Response Body pane, complete the following fields:
HTTP Code - Type a single HTTP status code or a code range to indicate the status of the response. Valid values are 100, 101, 102...599 or a range from 100-599.
Content Type - If the documentation of the SaaS provider specifies that the content type of the response body is JSON, select application/json as the content type. If the documentation of the SaaS provider specifies that the content type of the response body is XML, select application/xml as the content type. If the documentation of the SaaS provider specifies that the content type of the response body is binary, select binary as the content type. These options allow you to control the content in an HTTP response body.
Document Type - Select a Document Type for the Response Body or click Create Document Type to create a new Document Type. See Creating Document Types from Scratch.
Note:
Document Types created for a REST Application do not appear in the Develop > Document Types screen but appears only in the Document Types panel for the selected REST Application.
Error Response - You can handle HTTP errors by selecting this option. If you select this option, then during the execution of an operation, if you receive a corresponding status code as response from the back end, an exception appears. For example, if you create the resource with status HTTPs code as 300-500 identified as error response, then during execution, if you receive any response from 300-500, the operation execution will be considered as failure.
7. Click Save.
The Action appears in the Define Resources and Actions page. You can Edit or Delete the Action from the Define Resources and Actions page.
Note:
Do not edit or delete an Action if it is already used in an Operation. If the Action is edited or deleted, the Operations that are dependent on the Action including the Integrations that are dependent on the affected Operations, will not function properly.
8. Click Next.
The Confirm REST Application page appears.
9. Click Finish to create the REST Application.
The new REST Application appears in the REST Applications page.
10. To edit the REST Application, click the REST Application link and then click Edit Application. You can change the Description and Application Icon. After you click Finish, the Update REST Application window appears, which provides a summary of the impacted Accounts, Operations, and Integrations. Click Update to update the REST Application. To delete the REST Application, click Delete Application.