Privacy laws are changing on May 25th, and your business could be affected, regardless of your location

Learn More About GDPR Compliance

How to Quickly Build a JSON Web API in DataFlex with Thriftly.io [13min]

[fa icon="calendar"] May 5, 2017 3:57:39 PM / by Antonio Perez

  Antonio Perez

Thriftly allows Dataflex, C# and Java programmers of any level to quickly build web APIs and publish them for public or private use. Applications written in languages such as PHP, Python, or Javascript can use JSON-RPC, SOAP, REST or a Binary protocol over HTTP or raw TCP transports to communicate with the Thriftly API. Developers and businesses can rapidly transition existing Windows desktop applications to a hybrid cloud architecture or build new APIs.

Let's build an 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.


Thriftly-API-Project - Build JSON-RPC, SOAP, and Thrift based API services

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.

Thriftly API Service
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-testing-api-protal.jpg

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-API-testing-interface-developed-by-mertech.jpg

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.



Thriftl Public Endpoint API Gateway

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 Thriftly Developer [Docs]
Licensing Thriftly Developer [Docs]

DataFlex Developers API Guide [Docs]


 

Learn to save tons of development time with thriftly.io

Get Free API Video Tutorials Direct to Your Inbox

 

 

Topics: DataFlex, How To's, Video Guides

Antonio Perez

Written by Antonio Perez

Software Developer at Mertech Data Systems, Inc.

Subscribe to Email Updates

Lists by Topic

see all

Posts by Topic

see all

Recent Posts