Configuring the request

Every call made with TTMSFNCRESTClient is described by its Request object. Instead of building a URL string and header block by hand, you set typed properties — host, path, query, method, headers, and body — and the component assembles the HTTP request for you. This chapter covers how to compose the target URL, choose the method, attach query parameters and headers, and send a request body. Authentication has its own chapter; see Authentication.

Composing the target URL

There are two equivalent ways to point a request at an endpoint. Assign the full URL and the component splits it into Host, Path, Port, and Query; or set those parts individually and the component builds the URL. Keep the protocol (https://) on Host and the leading slash on Path so the two join correctly.

procedure TForm1.ComposeURL;
begin
  { Option A - assign the full URL. The component splits it into Host,
    Path, Port and Query for you. }
  TMSFNCRESTClient1.Request.URL := 'https://jsonplaceholder.typicode.com:443/posts?userId=1';

  { Option B - set each part explicitly. Keep the protocol on Host and the
    leading slash on Path so the two are joined correctly. A Port of 0 uses
    the default HTTPS port (443). }
  TMSFNCRESTClient1.Request.Host := 'https://jsonplaceholder.typicode.com';
  TMSFNCRESTClient1.Request.Path := '/posts';
  TMSFNCRESTClient1.Request.Port := 0;
  TMSFNCRESTClient1.Request.Query := 'userId=1';
end;

Note

Port defaults to 0, which uses the standard HTTPS port (443). Set it only for services that listen on a non-standard port.

Choosing the HTTP method

Method is a TTMSFNCCloudBaseRequestMethod value. The client supports rmGET for reads, rmPOST for sends with a body, and rmPOSTMULTIPART for multipart form uploads. GetMethodString returns the active method as text, which is useful when logging.

Value	Use for
`rmGET`	Reading data; parameters travel in the query string.
`rmPOST`	Creating or updating data with a body in `PostData`.
`rmPOSTMULTIPART`	Uploading files or multipart form payloads.

Adding query parameters

You can set the Query string directly, but the QueryParameters collection is safer for anything dynamic. AddParameter appends a key/value pair and keeps Query in sync; assigning Query likewise rebuilds QueryParameters, so the two never drift apart.

procedure TForm1.AddQueryParameters;
begin
  TMSFNCRESTClient1.Request.QueryParameters.Clear;

  { AddParameter appends one key/value pair and keeps the Query string in
    sync. Use it instead of concatenating the query by hand. }
  TMSFNCRESTClient1.Request.QueryParameters.AddParameter('q', 'delphi');
  TMSFNCRESTClient1.Request.QueryParameters.AddParameter('page', '1');

  { Query now reads 'q=delphi&page=1'. Setting Query directly also rebuilds
    QueryParameters, so the two representations never drift apart. }
  ShowMessage(TMSFNCRESTClient1.Request.Query);
end;

Adding request headers

The Headers collection holds the HTTP headers sent with the request. AddHeader appends one Key/Value line; GetHeadersText returns the whole set as formatted text. Set Content-Type whenever you send a body, and a User-Agent for public APIs that reject requests without one.

procedure TForm1.AddRequestHeaders;
begin
  TMSFNCRESTClient1.Request.Headers.Clear;

  { AddHeader appends one Key/Value header line. Many public APIs reject a
    request without an explicit User-Agent, so set one here. }
  TMSFNCRESTClient1.Request.Headers.AddHeader('Content-Type', 'application/json');
  TMSFNCRESTClient1.Request.Headers.AddHeader('User-Agent', 'MyDelphiApp/1.0');

  { GetHeadersText returns the headers as formatted key/value lines, handy
    when logging exactly what will be sent. }
  Memo1.Lines.Text := TMSFNCRESTClient1.Request.Headers.GetHeadersText;
end;

Sending a request body

For rmPOST and rmPOSTMULTIPART, put the payload in PostData and declare its format with a Content-Type header.

procedure TForm1.SendPostData;
begin
  TMSFNCRESTClient1.Request.Clear;
  TMSFNCRESTClient1.Request.Method := rmPOST;
  TMSFNCRESTClient1.Request.Host := 'https://api.example.com';
  TMSFNCRESTClient1.Request.Path := '/v1/items';

  { PostData is the body sent with methods that carry a payload (rmPOST,
    rmPOSTMULTIPART). Declare the body format with a Content-Type header. }
  TMSFNCRESTClient1.Request.Headers.AddHeader('Content-Type', 'application/json');
  TMSFNCRESTClient1.Request.PostData := '{"name":"Widget","quantity":5}';

  TMSFNCRESTClient1.ExecuteRequestWithResultString;
end;

Putting it together

A real request usually sets several of these parts at once. The example below combines the method, URL parts, a query parameter, headers, and a JSON body in a single configuration before sending.

procedure TForm1.BuildCompleteRequest;
begin
  TMSFNCRESTClient1.Request.Clear;

  { Method + URL parts. }
  TMSFNCRESTClient1.Request.Method := rmPOST;
  TMSFNCRESTClient1.Request.Host := 'https://api.example.com';
  TMSFNCRESTClient1.Request.Path := '/v1/orders';

  { Query parameters. }
  TMSFNCRESTClient1.Request.QueryParameters.AddParameter('notify', 'true');

  { Headers. }
  TMSFNCRESTClient1.Request.Headers.AddHeader('Content-Type', 'application/json');
  TMSFNCRESTClient1.Request.Headers.AddHeader('User-Agent', 'MyDelphiApp/1.0');

  { Body. }
  TMSFNCRESTClient1.Request.PostData := '{"sku":"WIDGET-1","quantity":3}';

  TMSFNCRESTClient1.ExecuteRequestWithResultString(
    procedure(AResponseString: string)
    begin
      Memo1.Lines.Text := AResponseString;
    end);
end;

Common mistakes

Splitting host and path incorrectly. If Host includes part of the path (or Path omits its leading slash), the assembled URL is wrong. Prefer assigning the full URL when in doubt and let the component split it.
Forgetting Request.Clear between reuses. The same client is often reused for different calls. Call Clear first so a previous query, body, or header set does not leak into the next request.
Body without a content type. Sending PostData without a matching Content-Type header makes many servers reject or misparse the payload.

Table of Contents