5 Minute Snack: Retrieve data from a RESTful API and import into a dataset using the REST library (I/II)

I must admit this is the one feature that really blew my mind, having worked with Visual Studio and Xcode often rather recently. This is so well-thought trought and abides to the ideas of REST so well that it made me reconsider a lot of my implementation considerations. Before knowing about this feature, I would go to Winforms when writing a quick client that needed to have a grid of some sort with user interaction for sorting and filtering. Delphi made me reconsider this position.

This blog post will not get you familiar with what REST is. Wikipedia has a wonderful page that introduces REST and its principles. Please go there first if this is the first thing you hear about REST.

We  start with a VCL Forms application and dvie right in. Drop the following components:

• TRESTClient, name it Client
• TRESTRequest, RequestLookup
• TRESTResponse, ResponseLookup
• TRESTResponseDatasetAdapter, AdapterLookup
• TClientDataset (or TFDMemTable), tblLookup

TRESTClient will provide the base for all of the services that we want to use from the REST API. As we know with REST APIs we have a base URL. From that base URL we access resources and one level below that we can access an element in that resource. We can go down as much as we want in that hierarchy.

In our example we will access the API from TVMaze.com. TVMaze is an amazing site that has all the information a couch potatoe needs…. I am very much into TV series and always need to look up episode information. TVMaze offers a free API that you can use to get information on any TV show there is.

As this is a 5 Minute Snack, we will just get a list of shows that matches a search pattern. Reading the documentation we know that we need to access

/search/shows?q=:query

in order to get a list of matching shows. The result will be in JSON format. Perfect.

Thus, we set up the TRESTClient BaseURL as follows:

We will initiate our request to the API using TRESTRequest and thus set its propeties as follows:

Set the Client property to “Client” component and the Response to “ResponseLookup”.

For Resource we specify “search” and the ResourceSuffix is “shows?q={title}”. With the braces “title” becomes a parameter and thus when clicking the Params “…” we will be able to configure the parameter:

Delphi recognizes that it is of tyoe “pkURLSEGMENT” and we only need to provide a value for design time purposes. I entered “Trek”. In code we will be able to change the value, of course.

Almost done. The data adapter needs to be connected:

Set the Response and Dataset properties as above. Also check “NestedElements” and we are really done already. Right-click the Request component and select Execute. It will yield a message box saying “200 – OK”, which means that the request succeeded.

Drop a TDataSource on the form and connect it to the dataset. Finally, drop a TDBGrid on the form and assign its datasource to the TDatasource you dropped before.

If you set the Active property of the Adapter to “True”, you will get the following result:

It’s amazing, eh? Totally useful information from a webservice within minutes inside a dataset. Any Delphi developer is able to use data that is in a dataset.

The next 5 Minute Snack will deliver the source code for run-time to offer the user the means to enter the series title. Until then, feel free to try for yourself if you can get it done.

The final application will look like this…. and took less than 20 minutes to write: