web analytics
Press "Enter" to skip to content

Creating your first Web Service with Composable DataFlow.

Sergey Kostenko

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” module responds back with requested data.

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

Now let’s fill in the UriIn parameter of the “Web Receive” module. UriIn is the link that will be used to access your WebService from the internet and will be constructed from three parts. First, the stem of this link must be a composable instance you are on. In case you are running your Composable on localhost it will be http://localhost/CompApp and can be found in the Browser Address Bar. Second part is the location of the web activation service and in most cases it is ~/services/WebActivationService.svc/Activate?appId=xxx. And the third and the last part is your AppId. To find your AppId, save your DataFlow first and AppId will appear in the Browser Address Bar. Insert the final result of your UirIn into the “Web Receive” module. Your final Uri will look similar to http://localhost/CompApp/services/WebActivationService.svc/Activate?appId=205718. 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.

Last step to make your WebService accessible to authenticated users is to authorize access for those users to your DataFlow. On the left of your app, go to DataFlow -> Share. Pick a group that you are modifying permissions for (either Everyone or Anyone with an Account) and change Execute permission to Allow. Then save on top right. Example is in the picture below.

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%20Timeand 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 “Web Receive” module that we added before. In the field “Handle” add “getTime”. Then, in your Uri 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 move your Composable app between environments it changes your DataFlow appIds. E.g. if you have clients or services that use your WebServices while it is in a Development environment and then you move it to Test or Production environment, you will have to manually update appIds. Using handles prevents you from needing to do it since they are consistent across different 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

Also, if you would like to learn more about creating WebServices or if you would like to see other examples, you may do so by watching two videos: “Building Web Services with Composable Data Flows” parts 1 and 2. You can find these videos in top right corner of your Composable app -> (i) -> “How-To Videos”.