Thursday, 21 August 2014

Introducing the REST Debugger....

- or How I helped a friend make his first REST client.

A good friend of mine, had finally decided to do some REAL programming :-D - and had for that purpose purchased a Delphi XE6 - and being relative new to the environment and hadn't looked into Delphi since version 7 - it is my privilege to help him getting started.

I had hoped for a "hello world" scenario, but he actually wanted to try to start off with a REST client against something like Google Translate.

The last time I did a web-service call to a "translation" service - was for a demo, back in 2001-2002 probably using Delphi 6 (introduced SOAP support - as I remember it) and the old BabelFish web-service.

I did a bit of digging and found out that many of the service are either gone or only have paid services - Google also did a cleanup in their many API's a couple of years back and ended making the Google Translate API a paid service - not that it is that expensive - but we where just looking something to play around with. Some web-service provides have test API-keys, which enable you to try out their stuff before you have over your credit card.

But one place to look for web-services is (I liked the site better before they where bought by MuleSoft last year - but it is still a very usable site). I also remembered that the online dictionary had a simple REST API available for free - so that was what we went for.

Doing REST clients in Delphi has been getting easier - starting with just an TIdHTTP component and some manual parsing of request and response, but still easily doable - to the new REST components that wraps the tiresome parts.

I had been using the new REST components, but it wasn't until I attended Jim McKeeth's excellent Developer Skill Sprint about Integrate Cloud Services with the REST/JSON Client, that I noticed the REST Debugger - I disagree on the naming since, as you will see it is more of a wizard used prior to any bugs needs to be debugged - and the name also explains why I hadn't noticed it in the first place - since I don't do bugs - no need for a debugger.

I haven't used that kind of "artificial" tools since the good old days of Turbo Analyst - not true.

The "Debugger"

The Glosbe API has 3 functions - translate, tm (translation memory) and addTranslation - initially I wanted to go for the translate function - but the response you end up receiving, can have quite a bit of information, so to keep things simple we went for the tm function.

So we started off with a new project (either VCL or FMX), and opened the REST Debugger found under the Tools menu in the IDE.

Based on the info from the Glosbe documentation page, we added the base or endpoint URL as

On the Parameters tab, we entered the function name as the resource, and the 4 required parameters for the function. Note that the language codes used are ISO 693-3 three letter language codes.

We then did a Send Request, went to the Body tab of the Response section and noted that the part or node we had interest in was the "examples" element, which we then applied as JSON Root Element.

Everything seemed to work, so we actually went to the Tabular Data tab and used the "Copy Components" button, which will put the components you need on the clipboard. Notice that if you are not on the Tabular Data you will not get the TRESTResponseDataSetAdapter and the TFDMemTable (you can of cause add those by hand later if you need them).

The "design"

Closing the REST Debugger and pasting the clipboard content to our empty form, left us only to add a TEdit, a TButton, a TDBGrid and a TDataSource.

After some moving around, alignments, anchoring and property setting we ended up with something like this, after we did a right-click on the TRESTRequest and did an execute - so that we have data in design time:

The TDatasource is connected to the FDMemTable and the TDBGrid is connected to the TDatasource, we could have used live bindings, but I wouldn't go into that on our first session.

The "Code"

The only thing missing was to add some functionality to the button, so on the TButtons onClick event, we changed the "phrase" parameters of the request to the content of the TEdit field. And execute the request.

procedure TForm1.Button1Click(Sender: TObject);
  RESTRequest1.Params.ParameterByName('phrase').Value := Edit1.Text;

Done - looking for food examples.

Notes and source

Be aware that the example are using the translation memory function, that grabs various examples of translated usage of the phrase we are looking for - using Glosbe's translate site or the translate function will give you a more "Google translate" experience - but Glosbe has some extra features that I think is nice - like the meanings, examples and audio playback for some words. I guess it is still "Alpha" - but open and community driven.

Also if you would like to look more into the parsing of the more complex JSON response from the translate function, watch Jeff Lefebvre's Skill Sprint from today and look into the use of the TJson class.

This posting was meant as a help for my friend, to describe what we actually did last night - and for others to "discover" the nice REST Debugger.

Source code