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