Creating REST API nodes

Creating the custom node

While developing your application, you might need access to 3rd party APIs or internal RESTful APIs of your other applications. If the needed node is not in the marketplace, you can create your own custom RESTful API nodes and use them in your application services. Additionally, you can also submit your custom nodes to the marketplace so that other Altogic platform users can use them.

To create a custom node via the Designer, you need to navigate the App settings and then to Custom nodes view.

In Custom node view, select New node, and from the dropdown list, select REST API node. The "Create REST API node" dialog will be displayed.

Creating a custom node has many different steps, and in each step, you configure different parts of your new node. Therefore, it is better to explain the custom node creation through an example. In this example, we will be creating a custom node to send an SMS message to a phone number using Twilio's Send SMS Message REST API. To send an SMS message through Twilio, you need the following input:

• Twilio account security identifier, which is a number used to identify you in Twilio. You need to create an account in Twilio to get this security identifier.
• Twilio authentication token, which is used to verify your identity and grant access to Twilio API features. You need to create an account in Twilio to get this authentication token.
• To, namely, the destination phone number for your SMS message.
• From, specifies the Twilio phone number, shortcode, or Messaging Service that sends this message. This must be a Twilio phone number that you own, formatted with a '+' and country code, e.g., +16175551212
• Body, which is the full text of the message you want to send, limited to 1600 characters

Step #1 - Specify custom node name and description

In the first step, give a descriptive name to your node, displayed in the Nodes Library panel and as your node's title in service flow. It is also good to provide a description of what your node does and its key input parameters.

Step #2 - Define input link points of the node

In this step, we define the input link points of our custom node. How many input link points will this node have, and what will be their type. We will have one fixed input object link point, but the service designer will be able to add dynamic input link points to this node except the list link points.

Step #3 - Define output link points of the node

In this step, we define the node's outputs, namely what data our node will return as a result of its execution.

Below is an example response JSON from Twilio's Send SMS Message API. If we would like to use this response in our services, we need to define a custom response model. If we are not interested in Twilio's response, we can set our output link point's type to trigger. In this example, Twilio returns a JSON object as a response and we define an output "object" link point.

info

Sometimes you may want to return a sub-object of the response. In this case, you define your custom response model using the sub-model definition, not the top-level response model definition, and specify the response model path expression for the sub-model.

For example, in the above JSON example, Twilio returns "subresource_uris," and for any reason, you would like to return only subresource_uris instead of the whole response data, then you need to define your custom data model only for "subresource_uris," which is basically an object with one string field called "media" and set the response model path to ["subresource_uris"]

Step #4 - Define node parameters

In this step, we define all the required input parameters of our node. These parameters will be displayed at the node's properties panel, and the users will need to provide input to these parameters, at least to the required ones. For sending the SMS message, we will define the following 5 input parameters:

Properties panel title	Parameter name	Properties panel widget	Type
Twilio Account SID	accountSID	Expression	Text
Twilio Auth Token	authToken	Expression	Text
To phone number	to	Expression	Text
From phone number	from	Expression	Text
Message body	body	Text Edit

For the first 4 parameters, we will be using the expression editor widget to capture inputs, and for the last parameter, we will use the text editor for input.

Step #5 - Set method, endpoint, and authentication method

In this step, we define the RESTFul API method, path, and authentication method for our send SMS service. Twilio's Send SMS RESTful API uses the POST method, and its endpoint includes the Twilio Account SID in its path. This API also supports HTTP Basic authentication where the username is the Twilio Account SID and the password is the Twilio Auth Token.

Step #6 - Add query parameters

The next step is to add query parameters to the RESTful API call request. In our send SMS example, we do not have any query parameters and will skip this step. However, if you need to add query parameters, you can add them as key-value pairs. These parameters are then appended to your endpoint path before making the request to the RESTful API.

Step #7 - Add HTTP headers

If the RESTful API that you are calling requires specific HTTP headers, then this is the step that you can add these additional headers. We do not have any additional headers in our example, and we will also skip this step.

Step #8 - Specifying request body

This is the step where we define the request body of our RESTful API call. In our case, sending a new SMS message requires 3 request body parameters, Body, From, and To, all in URL encoded format.

Step #9 - Confirm and create the new custom node

The final step is where Altogic runs validations on your custom node design and shows validation results. If there are no validation errors, you can select Finish to create your custom node. Otherwise, you need to return to the error step and fix them.

Using the new custom node

The custom node you have created in previous steps becomes available in the Nodes Library panel, and you can start using it in your service designs. The node parameters you have defined at Step #4 are also displayed in the Node Properties panel for input.