REST Request for Delphi

RESTRequest4Delphi is a REST request facilitator made for applications built in Delphi. With it, we eliminate the TRESTClient components: TRESTResponse, THTTPBasicAuthenticator and TRESTRequest. For ease of use, RESTRequest4Delphi uses the Fluent Interface / Fluent API (how to name methods to be used with the impression that you are writing a text).

Prerequisites

dataset-serialize - This is a DataSet serializer for Delphi
[Optional] For ease I recommend using the Boss for installation
- Boss - Dependency Manager for Delphi

Installation using Boss (dependency manager for Delphi applications)

boss install github.com/viniciussanchez/RESTRequest4Delphi

Manual Installation

Add the following folders to your project, in Project > Options > Resource Compiler > Directories and Conditionals > Include file search path

../RESTRequest4Delphi/src/core
../RESTRequest4Delphi/src/interfaces

Getting Started

You need to use RESTRequest4D.Request.Intf and RESTRequest4D.Request

uses RESTRequest4D.Request.Intf, RESTRequest4D.Request;

Method

Use Request.GetMethod method to get the method set. rmGET is default parameter.

begin
  Request.SetMethod(rmGET); // Use REST.Types
end;

URL

You can set the URL in several ways. Use the one that suits you.

begin
  Request.SetBaseURL('http://localhost:8080/datasnap/rest/servermethods/method');
  Request.SetBaseURL('http://localhost:8080/datasnap/rest').SetResource('servermethods/method');
  Request.SetBaseURL('http://localhost:8080/datasnap/rest').SetResource('servermethods').SetResourceSuffix('method');
end;

To get the values set use:

begin
  Request.GetBaseURL;
  Request.GetResource;
  Request.GetResourceSuffix;
  Request.GetFullRequestURL(True);
end;

In the GetFullRequestURL method the parameter indicates whether to add the parameters. Default is True.

Body

You can assign the request body with different types of parameters (strings, JSON and objects). To clear the body of a request, simply use Request.Body.Clear. The second parameter indicates who is responsible for destroying the object. Default is True. See the samples:

begin
  Request.Body.Add('Any thing');  
  Request.Body.Add(TJSONObject.Create, True);  
  Request.Body.Add(TObject.Create, True);
end;

DataSet Adapter

You can add a dataset to adapter. The contents of the request will be loaded into the dataset. We recommend using TFDMemTable.

begin
  Request.SetDataSetAdapter(FDMemTable);
end;

You can get the dataset as follows:

var
  LMemTable: TFDMemTable;
begin
  LMemTable := Request.GetDataSetAdapter as TFDMemTable;
end;

Headers

You can add headers. To clear the headers, use the Request.Headers.Clear. When you add a headers with the same name, its value changes. See the samples:

begin
  Request.Headers.Add('Accept-Encoding', 'gzip');
end;

Parameters

You can add parameters. To clear the parameters, use the Request.Params.Clear. When you add a parameter with the same name, its value changes. See the samples:

begin
  Request.Params.Add('country', 'Brazil');
end;

Basic Authentication

You can add a basic authentication to the request. To remove the authentication use Request.Authentication.Clear.

begin
  Request.Authentication.SetUsername('user').SetPassword('password');
end;

JWT - JSON Web Tokens

Here's an example of how to add the token generated by JWT in your request. To generate the JWT token, see the delphi-jose-jwt repository

begin
  Request.Params.AddHeader('Authorization', 'JWT Token', [poDoNotEncode]);
end;

Execute

The Execute method will return the Status code. See more in HTTP Status Codes

begin
  Request.Execute;
end;

Execute asynchronous

Executes a request asynchronously, i.e. run it in its own thread. There is no automatic serialization o property access though, which means that while the execution thread runs, properties of all involved TCustomRESTClient and TCustomRESTRequest instances should not be touched from other threads (including the main thread)

Using ExecuteAsync is strongly recommended on mobile platforms. iOS (and likely Android) willterminate an application if it considers the main thread to be unresponsive, which would be the case if there is a running request which takes more than a second or two to return.

The idea behind this is that the UI runs in the main thread and mobile devices should respond to user interaction basically immediately. Sluggish behaviour (caused by blocking the main thread) is considered unacceptable on these small devices.

You can pass parameter:

ACompletionHandler: An anonymous method that will be run after the execution completed.
ASynchronized: Specifies if ACompletioHandler will be run in the main thread's (True) or execution thread's (False) context.
AFreeThread: If True, then the execution thread will be freed after it completed.
ACompletionHandlerWithError: An anonymous method that will be run if an exception is raised during execution.

type
  TMyCompletionHandlerWithError = TProc<TObject>;

implementation

var
  LMyCompletionHandlerWithError: TMyCompletionHandlerWithError;
begin
  LMyCompletionHandlerWithError := procedure(AObject: TObject)
    begin
      if Assigned(AObject) and (AObject is Exception) then
        raise Exception(AObject); // or whatever you want!
    end;
  Request.ExecuteAsync(nil, True, True, LMyCompletionHandlerWithError);
end;

azrael11/RESTRequest4Delphi