How to build a fast JSON web API in DataFlex with Thriftly.io

Thriftly allows DataFlex programmers of any level to quickly build web APIs and publish them for public or private use. Outside applications written in any language (including PHP, Python, or Javascript) can communicate with your Thriftly API using a number of protocols (including JSON-RPC) and HTTP or TCP transports. Below, we'll walk you through how to use Thriftly to create a JSON web API in DataFlex.

1. Installing Thriftly on Your Machine

First, you will need to create a Thriftly.io account, download the development version and request a trial license. If you haven’t installed Thriftly, follow the Installing Thriftly Developer [Guide] to register your license in Developer Assistant.

2. DataFlex Project Setup

Now that you have Thriftly installed, we will create a sample String Service API that will manipulate strings. We will need to create a new Thriftly API project in order to initialize the Thriftly Server and publish the functions that will define the API. Create a Thriftly API project in your workspace.

Create Thriftly Project

The Thriftly developer installation installs example projects at
C:\Users\{YOUR USER}\Documents\Thriftly

Additionally, you can open ThriftlyLib.sws in DataFlex and run the ThriftlySample project to see a Thriftly API split into multiple services.

NOTE: If you are running a DataFlex version older than 18.2, you’ll need to adjust the Version configuration by opening the ThriftlyLib.sws in a text editor.

//-------- START Thriftly ASC PROJECT SRC FILE -------- 
Use Windows.pkg
Use cApplication.pkg
Use Thriftly.pkg
//#INCLUDE Mertech.inc

Object oApplication is a cApplication
    Set pbPreserveEnvironment to False
End_Object

// Login "(localdb)\MSSQLLocalDB" "" "" "SQL_DRV"

Object oThriftly is a cThriftlyServer
    Function ThriftlyWSError String sErrorMessage Variant retVal Returns Variant
        Error DFERR_OPERATOR sErrorMessage
        Function_Return retVal
    End_Function
    
    Use StringService.pkg
    //use ArrayService.pkg
End_Object

Send StartServer of oThriftly
//-------- END Thriftly ASC PROJECT SRC FILE --------

Send StartServer of oThriftly

The main object that we will be using is the cThriftlyServer which is where we will define our Thriftly API functions. After we are happy with the definition, we will start the oThriftly service by calling the StartServer procedure.

3. Defining Your API

Now that we have the basic skeleton for a Thriftly API in our DataFlex workspace, we need to define our API. Create a new Thriftly Service class by going to
File ->New ->Class and call it StringService.pkg.

Create Thriftly API Service class

//-------- Start Thriftly ASC StringService.pkg //--------

//include predefined logic from a package or file
Use cThriftlyService.pkg

Object oStringService is a cThriftlyService
    // psServiceName is the published name of this Service.
    // If you do not set a service name, the object name (minus the leading "o")
    // will be used as your service name.
    Set psServiceName to "StringService"

    {Published=True}
    Function JoinStrings String s1 String s2 Returns String
        Move (trim(s1)) to s1
        Move (trim(s2)) to s2
        
        If (s1="") Begin
            Function_Return (ThriftlyWSError(Self, "String 1 Must Be Defined", s1))
        End
        
        If (s2="") Begin
            Function_Return (ThriftlyWSError(Self, "String 2 Must Be Defined", s2))
        End
    
        Function_Return (s1 + " " + s2)
    End_Function
    
    {Published=True}
    Function ToUpper String string1 Returns String
        Move (Trim(string1)) to string1
        If (string1="") Begin
            Function_Return (ThriftlyWSError(Self, "String 1 Must Be Defined", string1))
        End
        
        Function_Return (Uppercase(string1))
    End_Function
End_Object

//-------- END Thriftly ASC UserService.pkg --------

In the StringService.pkg, we will see an object of oStringService of type cThriftlyService. The Thriftly Service object is where defined portions of your code will be exposed as an API. We will define this service as ‘StringService’. You expose the function as an API call by adding the {Published=True} annotation right above your function. It will be published under the service we just defined. Include the ServiceString package inside the oThriftly server object. Our joinString function will now be exposed as an API.

A Thriftly project could contain multiple services. The oThriftly object has a few commented out .pkg files that are there to showcase how you would include multiple Thriftly service packages within the Thriftly Server object. Splitting up your API into multiple services will allow you to modularize your code within their respective scope. For example, a string service API should be independent of an array service API.

At this point, we are ready to test the API call by compiling the application in DataFlex and starting the Thriftly Server. You will see the API interface where test data is sent to your API through a browser interface in JSON-RPC or SOAP.

4. Testing Your API

Thriftly Developer

When you start the DataFlex application, a Thriftly developer window will appear with different available settings.

Here you will specify the type of protocol an application will need to use to communicate with your API and transport method. If the ‘enable gateway’ is left unchecked, you can specify the port number that your application will run on.

When you start Thriftly without a Gateway enabled, the testing interface will automatically be loaded in your default web browser. Without a gateway, the API will only be accessible on your localhost.

Thriftly APEye GUI

The new Thriftly API runs on a local port, but you have the option to make the API public by enabling Thriftly's API Gateway. When published, the application’s API is accessible by the web through an HTTPS web address. No additional firewall configurations required. With Thriftly, you define a function and add a ‘published’ meta-annotation tag on that function to expose it.

That’s it!

Let’s see how you would do it in DataFlex.

5. Consuming Your API

When you enable the gateway option, you will have the option to publish your application to one of the geographically dispersed servers. This means a developer or consumer can access your application through the published gateway API URL without additional network configurations on your end. and you are able to focus on software development! Choose the server closest to you for better performance.

After we start Thriftly with a gateway, a Gateway Address will be generated in the bottom box. The Gateway Address is the API specifications that can be shared with a developer. In order to test the API, copy the ‘Location’ URL to a browser or follow the ‘Test API’ link to the Gateway Endpoint Url. This same endpoint can be used to build web apps or mobile apps that interact with your data.

Thriftly Gateway

Thriftly supports standard formats to describe HTTP-based web services that are generated by appending a parameter to the Thriftly Endpoint.

A Web Service Definition Language output (WSDL) is generated by appending '?wsdl' to the end of the Endpoint URL or a Web Application Description Language (WADL) file by appending '?wadl'.

The outputted WSDL is used to generate the necessary Apache Thrift files for your application or a WADL file can be uploaded to Azure API management to import your API into Azure.

example-> localhost:8000/StringService?wsdl

Thriftly reduces your time to production by allowing you to focus on the thing that matters, your business logic. With the Thriftly Gateway, there is no need to worry about firewall or network settings when publishing your API.

You can put your mind at ease that your application can simultaneously handle the most trusted HTTP protocols in JSON-RPC, SOAP, REST and Thrift without any code changes. Your existing Windows desktop applications will rapidly transition to a service model and bring in additional revenue.

Helpful Links:
Installing and Licensing Thriftly Developer [Docs]
DataFlex Developers API Guide [Docs]

Download our Free Guide for ISVs.
Learn to generate new revenue streams, go to market quickly, and acquire new customers.