web analytics

Creating your first Web Service with Composable DataFlow

The WebService we’ll be creating is a simple API endpoint that accepts a Time Zone as a parameter and returns current date and time.

To create a Web Service, first create a new DataFlow and add two Modules: “Web Receive” and “Web Send”. You’ll see that both Modules are encapsulated in orange color to let you know that these Modules can be externally activated. “Web Receive” listens for Get/Post request and “Web Send” responds back with requested data.

Constructing your Uniform Resource Identifier (a.k.a. Uri)

Every DataFlow containing a “Web Receive” Module is accessible through both GET and POST requests at the specified REST endpoint. The API endpoint URI, referred to as UriIn parameter in the Module, is formed from three components:

<instance name><web service location><app identifier>

  1. Instance Name: The stem of the link represents the Composable instance, typically accessed at https://your-instance/Composable/. You can easily locate this in the Browser Address Bar.
  2. Web Activation Service Location: The second part specifies the location of the web activation service: /services/WebActivationService.svc/.
  3. Application Identifier: The third and final part is the unique DataFlow Application identifier, along with the action to Activate it. The unique identifier can be in the form of the DataFlow ID or a DataFlow Handle, and is either: Activate?appId=xxx or Activate?appHandle=xxx . The DataFlow ID is available on the Designer or Details page (only after the DataFlow is saved). The DataFlow Handle is a unique name you can provide in the Module directly (described further below).

Putting all this together, the complete API endpoint for a given DataFlow, with Id 205718 or Handle MyDataFlow, and runnning on a local instance, e.g., http://localhost/CompApp/, will look like this:

(when using ID): http://localhost/CompApp/services/WebActivationService.svc/Activate?appId=205718

(when using Handle): http://localhost/CompApp/services/WebActivationService.svc/Activate?appHandle=MyDataFlow

Refer to the accompanying image for a visual representation of the resulting DataFlow configuration.

NOTE: While not required, it is useful to fill in the UriIn parameter of the “Web Receive” Module with this url so that you can run the DataFlow in the designer for debugging purposes.

Your DataFlow end result will look similar to the one on the picture below.

Now to retrieve current Date and Time, add the module “Get Present Date/Time” and connect its output to “ResponseIn” of the “Web Send” Module, like in the picture below. Then save your DataFlow.

The last step is to make your WebService accessible to authenticated users. To authorize access for those users to your DataFlow, you simply need to ‘Share’ the DataFlow with the approrpriate users or groups. On the left of your app, go to DataFlow -> Share. Pick a group that you are modifying permissions for (including either of the two built-in groups: ‘Everyone’ or ‘Anyone with an Account’) and change Execute permission to Allow. Then save on top right. If you allow Execute access to the ‘Everyone’ built-in group, as shown below, you are effectively providing anonymous acces.

Now, your WebService is accessible online through the Uri that you constructed in the “Web Receive” Module.

Accepting and processing parameters

To specify a time zone, simply modify Uri to accept parameters by adding &zone= at the end. Your final UriIn will look similar to this:

http://localhost/CompApp/services/WebActivationService.svc/Activate?appId=205718&zone=

To extract that parameter from Uri in DataFlow, add another Module to your DataFlow called “Uri Param Parser.” Connect result of Web Receive Module with Uri field of “Uri Param Parser” and result of “Uri Param Parser” to input of “Get Present Data/Time” Module. In the “Uri Param Parser” Module fill in fields “ParamName” with “zone” and “DefaultParamValue”(in case the user does not provide a parameter) with “UTC”. Save your DataFlow. Your result should look similar to the one below.

Now your Uri accepts parameters. For example, if you would like to get date and time in Mountain Standard Time time zone, just follow the link http://localhost/CompApp/services/WebActivationService.svc/Activate?appId=205718&zone=Mountain%20Standard%20Time and if you would like to get date and time in any other time zone just substitute Mountain%20Standard%20Time with the time zone of your choice. You may find the full list of time zones that are currently supported by the “Get Present Data/Time” Module in Module Details. Module Details may be accessed by clicking “?” on the top right corner any module.

Adding handle

Another helpful feature that is available to you in Composable is an ability to add a handle for your WebService. Using a handle is optional and may serve you in multiple ways: it provides consistent experience for your clients, less maintenance for you and it acts as a name for your WebService. To better understand handles let’s try using them based on our example. First, navigate to the “Web Receive” Module that we added before. In the field “Handle” add “getTime”. Then, in the Uri input, substitute appId=205718 with appHandle=getTime. Save your DataFlow. Your final Uri will look similar to this: http://localhost/CompApp/services/WebActivationService.svc/Activate?appHandle=getTime&zone= Now authorized users will be able to access your WebService using this Uri.

Using handle over appId has couple of benefits, especially for those who write large DataFlows:

  1. When you promote your Composable resources between environments, the DataFlow appIds will change. This means that if your API consumers (clients or services) use your WebServices while it is in one environment (e.g., Development environment) and then in another environment (e.g., Test or Production environment), they will have to update appIds. Handles on the other hand will remain consistent across environments.
  2. If you decide to use a different DataFlow for your WebService (change the way it is implemented), all you will need to do is to reassign an Uri with handle to a new DataFlow and your clients and services will have an immediate access to that service without the need to update their appIds.

Additional Resources

APIs play a vital role in application development, and Composable provides the ability to rapidly develop, deploy and maintain APIs.

If you would like to learn more about creating WebServices or if you would like to see additional examples, please view the following: Building Web Services with Composable Data Flows.