SYS-CON MEDIA Authors: Zakia Bouachraoui, Liz McMillan, Carmen Gonzalez, Roger Strukhoff, David Linthicum

Related Topics: PowerBuilder, Microservices Expo, Microsoft Cloud

PowerBuilder: Article

RESTful Web Services: A Quick-Start How-to Guide - Part 1

Coding a client to retrieve data from a response-oriented RESTful service

Among PowerBuilder 12.5 .NET's new features comes the ability to use WCF to call RESTful web services. This article, the first in a two-part series, provides a PowerBuilder 12.5 .NET developer with the foundational knowledge and skills to rapidly get up and running building PowerBuilder RESTful Web Service clients. Along the way I'll share with you a few tips and workarounds.

Introduction
PowerBuilder 12.0 .NET provided the ability to call SOAP-based web services using Microsoft's .NET 3.5 WCF API. I encourage those of you not familiar with WCF and SOAP to view my PowerBuilder WCF primer and StockTrader reference application overview hosted on Sybase.com. You can get to all my free tutorials from http://yakovwerde.ulitzer.com/node/1551687. New with version 12.5, along with an upgrade to WCF 4.0, is the ability to call RESTful web services, an increasingly popular mechanism for accessing remote resources in SOA applications. In this article I'll help you gain some foundational understanding and definitions, then familiarize you with the mechanics of coding a client to retrieve data from a response-oriented RESTful service. In Part 2, I'll explore the three types of request-oriented operations.

What Are RESTful Web Services?
In a nutshell, RESTful services are "web natural" and lightweight. They leverage HTPP's native GET, PUT, POST & DELETE methods to invoke service methods at well-known URIs. Much has already been written and is freely available on the Internet about the nature and implementation of RESTful web services and how they compare to SOAP/WSDL services. Instead of rehashing what has already been thoroughly described, Listing 1 provides a couple of web references from which you can glean an understanding of the technology. If you need more information, a quick search on your favorite search engine will turn up more references. If you're really serious and would like a full-sized book, you can purchase Jon Flanders' RESTful .NET published by O'Reilly.

  1. A Guide to Designing and Building RESTful Web Services with WCF 3.5
  2. Learn REST: A Tutorial

Listing 1: Useful Web References

One pragmatic difference between WSDL / SOAP services and RESTful services from the client viewpoint is the amount of onus placed on the client developer. SOAP services are fully described in a WSDL document, including their service methods, input parameters and return types. A PowerBuilder developer has no responsibility other than to input the WSDL location into the wizard or project painter and click the generate proxy button. The project painter does the rest. SOAP calls are also method based. At runtime the developer instantiates a single proxy and invokes specific methods as necessary. With RESTful services, however, the developer has more responsibility in defining the interface. He has to get hold of either a schema (XSD) document or .NET assembly that fully describes the types in the returned XML or JSON, OR a sample result set with sufficiently varied data to help the proxy generator decipher the return structure. He also has to know enough about the structure of the return type so as to be able to review the wizard's work and make corrections as necessary (more about this later). Calls to a RESTful service are not method based - simply navigating to the service URI with correct parameters appended gets you a response. This means there is one proxy per service (method), hence more code objects to maintain.

What Is JSON?
Depending on how they are implemented, RESTful web services can return data in one of several standard formats. Among the possible formats are XML, CSV, RSS, ATOM and JSON. PowerBuilder 12.5 allows you to choose either XML or JSON for your transfer format. What is JSON? The upshot is that JSON is a JavaScript / AJAX browser friendly data transfer format. Because AJAX is a pervasive web technology, many services are only available in JSON flavor. Listing 2 provides some useful references from which you can get more background on JSON.

JSON presents no problem for PowerBuilder! At design time you can provide a sample data set in JSON or XML format to the project painter. The project painter will parse the sample data, JSON data and generate the .NET reference objects you'll need to work with your data. At runtime JSON-based data transfer is parsed and converted to .NET value objects. The good news is that as a PB programmer you will not have to write JSON; however, you will have to read it to understand how a result set is constructed.

  1. Quick overview of this JSON
  2. JSON, a formal definition

Listing 2: Useful JSON References

Viewing JSON
IE 9 does not have a native facility for viewing JSON data. You'll need to use a tool to view the output data. One such tool is http://www.jsonviewer.com/. Once on the page, input the full invocation URL and click the ‘Get JSON and Parse' button. Figure 1 shows what you might see.

Figure 1: JSON Viewer

If you are using Fiddler to monitor HTTP traffic (http://www.fiddler2.com/fiddler2), install the JSON viewer.Figure 2 shows how you can view returned JSON objects in Fiddler.

Figure 2: Fiddler with JSON Viewer

Getting Started with PowerBuilder RESTful clients
Sidebar Tip:
PowerBuilder relies on tools from the .NET 4.0 SDK to generate many of the code artifacts your client application will need. At the time of this writing 12.5 is in beta release version. The installer does not install the .NET 4.0 SDK. You will need to download and install the .NET 4.0 SDK from Microsoft. If the SDK is not installed on your system, you will get an error message when you attempt to generate a proxy.

For this tutorial I'm going to the use the free GeoNames service located at www.GeoNames.org. The GeoNames geographical database covers many countries and contains over eight million place names that are available for download free of charge. GeoNames provides a robust set of RESTful services via which you can access their database. Figure 3 shows a partial listing of available services. You can find the full list of available services at http://www.geonames.org/export/ws-overview.html. To explore GeoNames on your own, you'll want to create a free user account using the Login link on the upper right side of their home page. Having an account is important since you'll need to provide your username as a parameter to your service calls and access using the "demo" user name is extremely limited.

Figure 3: Some GeoName Services

Getting Started
Here's a list of the information you'll need to have handy before entering inputs in the RESTful service project wizard:

  1. The name of PBL into which you want to save your project object (usually the same pbl containing the project object you use to generate you EXE).
  2. The name of PBL into which the project painter will generate the code for your proxy class (you may want a separate pbl just for proxies that you can batch refresh if need be).
  3. The web method type GET, POST, PUT or DELETE.
  4. A name for your proxy class. You will interact with this class in your code. I'd suggest using the P_ prefix as part of your name.
  5. A name for the NameSpace you want to put your proxy class in - you can leave it blank to use the default namespace.
  6. The URI for the service including any parameters needed for the call.
  7. The service's return data format: XML or JSON.
  8. A name for a generated assembly. This assembly will contain value objects used as parameters and/or return types. It will be added by the wizard to your target as a reference. This name will also become the namespace for the assembly.
  9. A source to help the painter determine the return data type. There are three options, choose one:
    - A schema document (XSD) that defines the structure of the returned dataset.
    - A preexisting assembly that formally defines the return type structure
    - A sample XML snippet or JSON object whose data is rich and robust enough that the tool can figure out the data types from its contents.

Sidebar Tip: As shown in Figure 4 you can cause the generator to include input parameters on the GetMessage( ) method by changing Service URL literal values to tokens. Identifiers inside {  } will become parameter names. If you leave the literal values in, the generator will emit a parameter-less method call.

Figure 4: Parameterizing the URL

Stepping though the Wizard
Creating a new proxy class is a two-step process. First, you run the wizard in order to generate the development time project object and reference assembly. Then you verify your inputs in the project painter and deploy the project object to generate your runtime code artifacts. Let me visually guide you through the process. For this example I'm going to do a GET on the GeoName findNearbyWikipedia service. Follow Figures 5 through 12 in sequence to overview the complete process.

Figure 5: Wizard - Step 1

Figure 6: Wizard - Step 2

Figure 7: Wizard - Step 3

Figure 8: Wizard - Step 4

Figure 9: Wizard - Step 5

Figure 10: Project Painter with generated project object

Figure 11: Click the Generate Button on the Painter Toolbar

Figure 12:  Generated Code objects

Sidebar Tip: The invocation method for a GET will always be named GetMessage( ). It is a good practice to include the service name as part of its corresponding proxy class name. This will make its intent clear.

Sidebar Tip: If you use a sample dataset (XML or JSON) to generate your reference assembly, it's important that you examine the emitted assembly to verify the data type of each property. Occasionally the Microsoft parser will misinterpret a property's type. You'll want to correct that before moving on. There is no intermediate source code for the reference assembly, so your only recourse is to supply values to the project object that will cause it to render the property correctly. For example, a supplied postalCode element with the value ‘07960' was generated as a UInt16 instead of the expected String type. Supplying the value ‘x7960' forced the type to be rendered as a String.

Generated Artifacts
Let's take a more in-depth look at the generated code artifacts. Figure 13 shows the three kinds of objects generated from a project object.

Figure 13: Generated code artifacts

Project Object is a place to input your choices and a front end onto Microsoft and PowerBuilder code generation tools. You click the Generate Proxy button on the Project Object's PainterBar to kick off the code generation process

Proxy Class is the class you instantiate in your code and use to call the service. Don't modify the generated code. Any changes you make to this code object will be lost when you regenerate your proxy. To extend or modify this code, inherit from this class and write your changes in the descendant. You instantiate a proxy type object and call GetMessage( ) passing appropriate parameters to invoke the service. Figure 14, shows the contents of a typical Proxy class fronting a call to a GET method.

Figure 14: Contents of a GET proxy object

Request and Response Assemblies contain value objects returned by a GET call or passed as parameters to DELETE, POST and PUT calls. The WCF infrastructure handles converting JSON & XML into value objects and vice versa. You are spared from dealing with low-level conversion issues. Usually there will be a wrapper object that may or may not have data properties. It's the equivalent of the root element in an XML document. The wrapper object will have an array of value objects. These are the repeating row-oriented XML structures. The value object will have some set of return specific data values. Figure 15 shows the contents of a typical Response Assembly.

Figure 15: Contents of a typical Response Assembly

Scripting the Call
The runtime code algorithm follows these steps:

  1. Instantiate the proxy in the appropriate scope.
  2. Declare return value reference variables.
  3. Call the GetMessage( ) method passing applicable parameters and capture the return.
  4. Destroy the proxy or let it go out of scope.

Figure 16 shows the complete code for a GET service invocation. Of course in a "real-world" application you will do something more significant with the return values than display them in a messagebox.

Figure 16: Complete code for a GET service invocation

Note that even in well-designed applications, things can go wrong that are outside the client developer's control. For example, at runtime a service can be down or totally unavailable at the known URI. Therefor even though exception handling is optional, it's a best practice to avoid runtime system errors by scripting service calls inside TRY CATCH blocks that include a robust handler for problematic conditions.

Sidebar Tip: Using a single line DataWindow expression to directly load a data buffer from a PowerScipt NVO array works great. However, directly assigning a .NET value object array to a DataWindow buffer using an expression throws a runtime error. As a result you have to take a more time and labor code intensive approach. You must either (a) iterate the .NET object array and call SetItem( ) for each value OR (b) assign the .NET value array to an equivalent intermediate PowerScript NVO type array and then assign it to a DataWindow.

Sidebar Tip: Unfortunately, Web Service DataWindow Objects are only SOAP compatible. They have not yet become RESTful aware. To use a DataWindow for data display, you'll need to declare an external data source DataWindow and manually populate its buffer from the RESTful WS call return.

Conclusion
RESTful services are becoming pervasive on the Web. The APIs of many popular services, such as Google are Yahoo, are available as RESTful services. PowerBuilder 12.5 .NET programmers now have the ability to integrate calls to RESTful services in their applications using standard tools and technologies.

Long Live PowerBuilder!

More Stories By Yakov Werde

Yakov Werde, a 25 year IT industry veteran, is a member of TeamSybase and the newly formed Sybase Customer Evangelist Team. Yakov is a recognized author, speaker and trainer who has been designing and delivering PowerBuilder, .NET, EaServer, Web App Development, and Java training for over 14 years to corporate, military and government developers. Prior to discovering his aptitude as an educator, Yakov worked as an architect, project manager and application coder in the trenches of application software development. Yakov holds a Masters in Education with a specialty in instructional design for online learning from Capella University and a BS in math and computer science from Florida International University. Yakov, managing partner of eLearnIT LLC (www.elearnitonline.com), authors and delivers workshops and web based eLearning tutorials to guide professional developers toward PowerBuilder Classic and .NET mastery. Follow Yakov on Twitter as @eLearnPB

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


Latest Stories
Moroccanoil®, the global leader in oil-infused beauty, is thrilled to announce the NEW Moroccanoil Color Depositing Masks, a collection of dual-benefit hair masks that deposit pure pigments while providing the treatment benefits of a deep conditioning mask. The collection consists of seven curated shades for commitment-free, beautifully-colored hair that looks and feels healthy.
The textured-hair category is inarguably the hottest in the haircare space today. This has been driven by the proliferation of founder brands started by curly and coily consumers and savvy consumers who increasingly want products specifically for their texture type. This trend is underscored by the latest insights from NaturallyCurly's 2018 TextureTrends report, released today. According to the 2018 TextureTrends Report, more than 80 percent of women with curly and coily hair say they purcha...
The textured-hair category is inarguably the hottest in the haircare space today. This has been driven by the proliferation of founder brands started by curly and coily consumers and savvy consumers who increasingly want products specifically for their texture type. This trend is underscored by the latest insights from NaturallyCurly's 2018 TextureTrends report, released today. According to the 2018 TextureTrends Report, more than 80 percent of women with curly and coily hair say they purcha...
We all love the many benefits of natural plant oils, used as a deap treatment before shampooing, at home or at the beach, but is there an all-in-one solution for everyday intensive nutrition and modern styling?I am passionate about the benefits of natural extracts with tried-and-tested results, which I have used to develop my own brand (lemon for its acid ph, wheat germ for its fortifying action…). I wanted a product which combined caring and styling effects, and which could be used after shampo...
Steaz, the nation's top-selling organic and fair trade green-tea-based beverage company, announces its 2017 "Mind. Body. Soul." tour, which will bring authentic experiences inspired by the brand's signature Mind. Body. Soul. tagline to life across the country. The tour will inform, educate, inspire and entertain through events, digital activations and partner-curated experiences developed to support the three pillars of complete health and wellness.
The precious oil is extracted from the seeds of prickly pear cactus plant. After taking out the seeds from the fruits, they are adequately dried and then cold pressed to obtain the oil. Indeed, the prickly seed oil is quite expensive. Well, that is understandable when you consider the fact that the seeds are really tiny and each seed contain only about 5% of oil in it at most, plus the seeds are usually handpicked from the fruits. This means it will take tons of these seeds to produce just one b...
The platform combines the strengths of Singtel's extensive, intelligent network capabilities with Microsoft's cloud expertise to create a unique solution that sets new standards for IoT applications," said Mr Diomedes Kastanis, Head of IoT at Singtel. "Our solution provides speed, transparency and flexibility, paving the way for a more pervasive use of IoT to accelerate enterprises' digitalisation efforts. AI-powered intelligent connectivity over Microsoft Azure will be the fastest connected pat...
There are many examples of disruption in consumer space – Uber disrupting the cab industry, Airbnb disrupting the hospitality industry and so on; but have you wondered who is disrupting support and operations? AISERA helps make businesses and customers successful by offering consumer-like user experience for support and operations. We have built the world’s first AI-driven IT / HR / Cloud / Customer Support and Operations solution.
ScaleMP is presenting at CloudEXPO 2019, held June 24-26 in Santa Clara, and we’d love to see you there. At the conference, we’ll demonstrate how ScaleMP is solving one of the most vexing challenges for cloud — memory cost and limit of scale — and how our innovative vSMP MemoryONE solution provides affordable larger server memory for the private and public cloud. Please visit us at Booth No. 519 to connect with our experts and learn more about vSMP MemoryONE and how it is already serving some of...
Darktrace is the world's leading AI company for cyber security. Created by mathematicians from the University of Cambridge, Darktrace's Enterprise Immune System is the first non-consumer application of machine learning to work at scale, across all network types, from physical, virtualized, and cloud, through to IoT and industrial control systems. Installed as a self-configuring cyber defense platform, Darktrace continuously learns what is ‘normal' for all devices and users, updating its understa...
Codete accelerates their clients growth through technological expertise and experience. Codite team works with organizations to meet the challenges that digitalization presents. Their clients include digital start-ups as well as established enterprises in the IT industry. To stay competitive in a highly innovative IT industry, strong R&D departments and bold spin-off initiatives is a must. Codete Data Science and Software Architects teams help corporate clients to stay up to date with the mod...
As you know, enterprise IT conversation over the past year have often centered upon the open-source Kubernetes container orchestration system. In fact, Kubernetes has emerged as the key technology -- and even primary platform -- of cloud migrations for a wide variety of organizations. Kubernetes is critical to forward-looking enterprises that continue to push their IT infrastructures toward maximum functionality, scalability, and flexibility. As they do so, IT professionals are also embr...
Platform9, the leader in SaaS-managed hybrid cloud, has announced it will present five sessions at four upcoming industry conferences in June: BCS in London, DevOpsCon in Berlin, HPE Discover and Cloud Computing Expo 2019.
At CloudEXPO Silicon Valley, June 24-26, 2019, Digital Transformation (DX) is a major focus with expanded DevOpsSUMMIT and FinTechEXPO programs within the DXWorldEXPO agenda. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive over the long term. A total of 88% of Fortune 500 companies from a generation ago are now out of business. Only 12% still survive. Similar percentages are found throug...
When you're operating multiple services in production, building out forensics tools such as monitoring and observability becomes essential. Unfortunately, it is a real challenge balancing priorities between building new features and tools to help pinpoint root causes. Linkerd provides many of the tools you need to tame the chaos of operating microservices in a cloud native world. Because Linkerd is a transparent proxy that runs alongside your application, there are no code changes required. I...