Ask Reuben

Starting With Genero Web Services (part 1 of 3)

What is Genero Web Services (GWS) ? 

What is a Web Service?

What is SOAP and RESTful? 

What is the difference between high-level and low-level Web Services?

When developers start using our newer products I often see them jumping in the deep end, trying to run before they can walk, biting off more they can chew etc. and their first experiences are not as positive as they can be. Over time I am going to do a series of articles entitled “Starting …” where I will explain what I think are the key concepts points you should understand with our products and try and make your initial experience a positive one. Today I will look at Genero Web Services (or GWS).

I will do this in three articles.  I will start off with an Introduction in this article and followup in following weeks with an article concentrating on the 4gl for the developers and a third article looking at hosting a Web Service for the system administrators.


No Separate Download or Documentation

First thing to note is that there is NOT a separate download or documentation for Genero Web Services.

The libraries required for Genero Web Services code are bundled inside the BDL download.

The hosting and management side of Genero Web Services for production is handled by the Genero Application Server (GAS). You will not need GAS for little developer tests but you will need it for production if you are the provider of a Web Service.


Web Services Roles

Second thing to note. When dealing with Web Services, you need to understand that there are two roles within a Genero Web Services. You need to understand if you  …

  • Server / Provider – are you providing the Web Service for someone else to consume ?
  • Client / Consumer – are you consuming or using someone else’s Web Service ?

The code you will write, the libraries you will use, are different depending upon whether you are the server/provider or the client/consumer. First thing you should ask yourself when dealing with a Web Service, am I the server or am I the client? Am I providing the web service for someone else to consume or am I consuming a web service provided by someone else?

If you are unsure, ask yourself this?

  • Am I making the request? If yes, you are the client/consumer.
  • Am I providing the response? If yes, you are the server/provider.
  • Is my program sitting and waiting for someone to connect. If Yes, you are the server/provider
  • Am I dictating the rules or someone is telling me the format of the data exchange. Normally the server/provider gets to dictate the rules. That is this is the URL to use, this is the format of the request to use and this is the format of the response

This concept of request and response, you will see in the name of classes and methods. You will also see it when analyzing logs. You will see a web service request made, and a web service response received.

This is an important distinction to get right at the beginning as it can get very confusing if you start off looking at the wrong set of libraries for the role your code is supposed to be performing.


SOAP v REST

Third thing to note, there are two software architectural styles of web services. You will hear the term SOAP and REST (RESTful). There are not our terms so I would suggest having read our pages, google around and see what else you can find about these.  Important thing to note is that Genero caters for both and that you will need to use the appropriate libraries.  If you are attempting to communicate with either, Genero should handle it.

I also find following these old articles interesting. Some of these links are nearly 20 years old but I don’t expect the conclusion to be any different.

https://aws.amazon.com/blogs/aws/rest_vs_soap/

https://web.archive.org/web/20060220125602/http://www.dotnetjunkies.com/WebLog/kevdaly/archive/2006/02/11/135202.aspx

https://web.archive.org/web/20060304134254/http://www.oreillynet.com/pub/wlg/3005?wlg=yes

When interacting with a web service, if the provider provides you a wsdl file, they are using SOAP, otherwise it is likely it is a RESTful Web Service.  Starting out I will use the REST libraries.

You should also note that Genero added the SOAP libraries before the RESTful libraries.


High-level versus Low-level

Fourth thing to note , is that within our Web Service libraries there is the concept of high-level and low-level. Web Services use the HyperText Transfer Protocol (HTTP) to exchange information. Our high-level libraries hide that from the Genero developer. You just have to write a Genero function like any other and the high-level libraries will formulate the request and response that will be transmitted across the network. Occasionally you may need to access the low-level libraries to access the content that is being transmitted and received.

You should start off aiming to use the high-level but for more advanced web services, or more likely for Web Services that don’t conform tightly to standards you may need to use the low-level libraries and manipulate the xml and json that is being send and received.


Tools

When developing and debugging  Web Services there are always the two sides to a web service as mentioned above.  It is not a requirement that both sides are Genero.  You can use Genero to consume a Web Service written in Java, .Net etc and vice versa.

In development, you may find it easier to have something else act as the other party in a web service, that is to simulate request and responses.  This maybe a tool such as Postman or you can go a query from the command line using curl.  I’ll show an example using curl in next article.

Also when interacting with third party API’s they often have a sandbox you can develop against.  If you are hosing a Web Service for others to consume, this is something you should consider as well.


Key Points

When dealing with Web Services, if you raise a support call you will need to know …

  • Am I the server/provider/responder or the client/consumer/requestor ?
  • Are you using SOAP or REST ?
  • Are you using high-level or low-level libraries/functions ?

Before starting I would encourage you to read the following sections of our BDL documentation.

Something else I encourage is going out into the real world and finding examples of web services.  When I first started out using web services, prominent providers had free web services you could use.  Over time, they have blocked the free access but if you want a good exercise , have a look at …

  • the Google Geocode Api as they are a good example you may end up incorporating in your application
  • find a name/address/postcode verification API for your country
  • find prominent accounting system API’s such as Xero, MYOB, QuickBooks.