Tutorial: Using the REST Client Library to Access REST-based Web Services

From RAD Studio
Jump to: navigation, search

Go Up to Database and LiveBindings Tutorials

This REST BaaS (Backend as a Service) client tutorial shows how to use the REST Client Library for accessing REST-based web services (REST stands for Representational State Transfer). The REST library is available for all platforms that are supported by Delphi. The REST Library framework focuses on JSON as the representation format. XML is not explicitly supported.

Creating the Project

Create a new project.

  • For Delphi, choose File > New > Multi-Device Application - Delphi > Blank Application.
  • For C++Builder, choose File > New > Multi-Device Application - C++Builder > Blank Application.

Adding the REST Components

  1. Drop the TRESTClient, TRESTRequest, and TRESTResponse components on the form.
    Tip: Alternatively, you can copy all these three components to the clipboard using the Copy Components button of the REST Debugger Tool, and then paste them to the form. This helps you speed up the work.
  2. In the Object Inspector, set the BaseURL property of the TRESTClient to http://www.songsterr.com/a/ra/.
  3. Select the TRESTRequest component on the form and set the following properties:
    • In the Object Inspector, set the Resource property to songs.json.
    • In the Structure View, expand the Params node.
    • Right-click the Params node, and click Add item on the context menu.
    • Under Params, click the newly added parameter 0-.
    • In the Object Inspector, set the parameter name to pattern, and the parameter value to Madonna.
      RESTTutorialStructureViewModified.png
  4. Right-click the TRESTRequest component and select Execute.
    RESTTutorialResponseOK.png
  5. Click the OK button.
Note: This scenario illustrates how to get a response from the Songsterr Web service in the JSON format. The Songsterr Web service also supports the xml and plist formats. For more information, see http://www.songsterr.com/a/wa/api.

Using the LiveBindings Designer

Open the LiveBindings Designer. The diagram with no connections is similar to the following image:

RESTTutorialLiveBindingsDesigner.png

  1. Right-click the RESTResponse1.Content property.
  2. Select the Link to new control option.
  3. From the list that appears, select the TMemo control.
    RESTTutorialBindNewControlTMemo.png
  4. Click the OK button.
  5. In the Object Inspector, set the following properties of the TMemo component:
    • Set the Align property to Client.
    • Set the TextSettings/WordWrap property to True.
      If you have called the Execute method of the TRESTRequest component, the TMemo should already display the RAW JSON results.
  6. Drop a TPanel component on the form.
  7. Set the Align property of TPanel to Top.
  8. In the LiveBindings Designer, right-click the Params.pattern property of the RESTClient1.
  9. Select the Link to new control option.
  10. From the list that appears, select the TEdit control, and click OK.
    Note: The Add control label check box is checked by default, and a TLabel is created for the TEdit control.
  11. Move the Params.pattern control to the top of the form.
  12. Add a TButton component on the form, and set the Text property of the button to Execute.

Preparing your Application for Run Time

Creating the Event Handler for the Execute Button

  1. In the Form Designer, select the Button1 component.
  2. In the Object Inspector, double-click the OnClick event.
  3. Add the following code to this event handler:

Delphi:

procedure TForm1.Button1Click(Sender: TObject);
var
  jValue:TJSONValue;
begin
  RESTRequest1.Execute;
  jValue:=RESTResponse1.JSONValue;
  MemoContent.Text:= jValue.ToString;
end;
Attention: The TJSONValue class is declared in the System.JSON unit. Before compiling this project, please add System.JSON to the uses clause of your unit.

C++Builder:

void __fastcall TForm1::Button1Click(TObject *Sender) {
    TJSONValue *jValue;
    RESTRequest1->Execute();
    jValue = RESTResponse1->JSONValue;
    MemoContent->Text = jValue->ToString();
}
Attention: The TJSONValue class is declared in the System.JSON library. Before compiling this project, please add #include <System.JSON.hpp> to the project header file.

Running Your Application

To run your application:

  1. Press F9 or choose Run > Run.
  2. Enter a pattern (such as Madonna) in the Param.pattern text box.
  3. Click Execute to send your request to the Songsterr service.


RESTTutorialRunTime2.png

See Also