TsgcOpenAPI_Client is a non-visual component that encapsulates the main methods and properties to make HTTP requests from an OpenAPI specification.
Every OpenAPI interface created with sgcOpenAPI Parser has 2 methods
Example
Use the Abstractapi to retrieve the localization of an IP Address.
GetOpenAPIClient.Retrieve_the_location_of_an_IP_address('your api', '80.258.15.2');
auth2Code: It's used to perform authentication and authorization in the majority of application types, including single page applications, web applications, and natively installed applications. The flow enables apps to securely acquire access_tokens that can be used to access resources secured, as well as refresh tokens to get additional access_tokens, and ID tokens for the signed in user.
auth2ClientCredentials: This type of grant is commonly used for server-to-server interactions that must run in the background, without immediate interaction with a user. These types of applications are often referred to as daemons or service accounts.
Read more about OAuth2.
Allows to configure how connect to secure SSL/TLS servers using HTTP/1 protocol
The generated clients verify the certificate of the server by default, earlier versions did not. The trust comes from the OpenSSL default verify paths, so on a machine where no CA store is configured, set TLSOptions.RootCertFile to the file with the trusted root certificates. To connect to a self-signed or test endpoint, set TLSOptions.VerifyCertificate := False.
ALPNProtocols: list of the ALPN protocols which will be sent to server.
RootCertFile: path to root certificate file.
CertFile: path to certificate file.
KeyFile: path to certificate key file.
Password: if certificate is secured with a password, set here.
VerifyCertificate: if certificate must be verified, enable this property. The OpenAPI client enables it by default, set it to False to accept a self-signed certificate.
VerifyDepth: is an Integer property that represents the maximum number of links permitted when verification is performed for the X.509 certificate.
Version: by default uses TLS 1.0, if server requires a higher TLS version, here can be selected.
IOHandler: select which library you will use to connection using TLS.
iohOpenSSL: uses OpenSSL library and is the default for Indy components. Requires to deploy openssl libraries for win32/win64.
iohSChannel: uses Secure Channel which is a security protocol implemented by Microsoft for Windows, doesn't require to deploy openssl libraries. Only works in Windows 32/64 bits.
OpenSSL_Options: configuration of the openSSL libraries.
APIVersion: allows defining which OpenSSL API will be used.
oslAPI_1_0: uses API 1.0 OpenSSL, it's latest supported by Indy
oslAPI_1_1: uses API 1.1 OpenSSL, requires our custom Indy library and allows using OpenSSL 1.1.1 libraries (with TLS 1.3 support).
oslAPI_3_0: uses API 3.0 OpenSSL, requires our custom Indy library and allows using OpenSSL 3.0.0 libraries (with TLS 1.3 support).
LibPath: here you can configure where are located the openSSL libraries
oslpNone: this is the default, the openSSL libraries should be in the same folder where is the binary or in a known path.
oslpDefaultFolder: sets automatically the openSSL path where the libraries should be located for all IDE personalities.
oslpCustomFolder: if this is the option selected, define the full path in the property LibPathCustom.
LibPathCustom: when LibPath = oslpCustomFolder define here the full path where are located the openSSL libraries.
UnixSymLinks: enable or disable the loading of SymLinks under Unix systems (by default is enabled, except under OSX64):
oslsSymLinksDefault: by default are enabled except under OSX64 (after MacOS Monterey fails trying to load the library without version.).
oslsSymLinksLoadFirst: Load SymLinks and do before trying to load the version libraries.
oslsSymLinksLoad: Load SymLinks after trying to load the version libraries.
oslsSymLinksDontLoad: don't load the SymLinks.
SChannel_Options: allows you to use a certificate from Windows Certificate Store.
CertHash: is the certificate Hash. You can find the certificate Hash running a dir command in powershell.
CipherList: here you can set which Ciphers will be used (separated by ":"). Example: CALG_AES_256:CALG_AES_128
CertStoreName: the store name where is stored the certificate. Select one of below:
scsnMY (the default)
scsnCA
scsnRoot
scsnTrust
CertStorePath: the store path where is stored the certificate. Select one of below:
scspStoreCurrentUser (the default)
scspStoreLocalMachine
Use this property to configure the connections through a proxy.
Enabled: set to true to enable proxy connections.
Host: Proxy server address
Port: Proxy server port
UserName/Password: Authentication to connect to proxy, only if required.
ProxyType: the following proxies are supported:
If Log property is enabled it saves socket messages to a specified log file, useful for debugging.
Log: enable if you want to save the HTTP requests to a text file.
LogFileName: full path to the filename.
Other properties that can be used to customize the OpenAPI client:
EncodeBodyAsUTF8: if enabled, the request body is encoded as UTF-8 (by default true). A JSON document is UTF-8 per RFC 8259, a body encoded as ANSI mangles every character outside the ASCII range.
The classes (DTOs) generated from the specification expose the following properties to customize how they are written to JSON:
JSONIgnoreEmptyStrings: by default it is False, so a field holding an empty string is written as "field": "". An empty string is a value and the server cannot tell it apart from a field that was never set. Set it to True to leave the empty strings out of the JSON, which is what earlier versions did.
JSONIgnoreNullValues: by default it is True, so a null is not written to the JSON. The nulls are controlled by this property alone, it is independent of JSONIgnoreEmptyStrings. Set it to False to write an explicit null, which is what a JSON Merge Patch (RFC 7386) needs to delete a member.
The result of a request is returned in a TsgcOpenAPIResponse object.
ResponseStream: stream where the body of the response is written, assign your own stream to save a download directly to it.
OwnsResponseStream: a stream assigned by the caller is no longer destroyed with the response, the caller keeps the ownership. Set it to True to restore the previous behaviour and let the response free the stream.
A parameter declared as in: cookie in the specification is supported. All the cookie parameters of a request are sent together in a single Cookie header, as RFC 6265 requires.
By default the OpenAPI client executes requests synchronously. Use the asynchronous API to run a request on a background thread and be notified through events, which keeps the user interface responsive and allows the request to be cancelled.
HTTP_REQUEST_Async: runs the request on a worker thread. The client takes ownership of the request object.
CancelAsync: cancels the request in progress.
SynchronizeEvents: when True the events are marshalled to the main thread. By default it is False and the events fire in the worker thread.
The result is delivered through the following events:
OnResponse: the request completed, the response is passed as a parameter.
OnError: the request failed, the exception is passed as a parameter.
OnCancel: the request was cancelled by CancelAsync.
The client cannot be freed from inside its own OnResponse, OnError or OnCancel event handler. Destroying it waits for the worker thread, which is the very thread running the handler, so the application would hang. A clear error is raised instead, free the client once the event handler has returned.
Find below the list of the events that you can handle when using the OpenAPI Client.
OnBeforeRequest
This event is called before the HTTP request is called. Allows to customize the Parameter names, Headers, security... Find below an example how to replace the name of some parameters.
procedure OnBeforeRequestEvent(Sender: TObject; const aRequest: TsgcOpenAPIRequest);
var
i: Integer;
oParameter: TsgcOpenAPIParameter;
begin
for i := 0 to aRequest.Parameters.Count - 1 do
begin
oParameter := aRequest.Parameters[i];
if oParameter._Name = 'meta-modified-from' then
oParameter._name := 'eventDateTime-from';
if oParameter._Name = 'meta-modified-to' then
oParameter._name := 'eventDateTime-to';
end;
end;
OnUpload
This event is called when a file is uploaded, you can use this event to know the progress of the upload.
OnDownload
This event is called when a file is downloaded, you can use this event to know the progress of the download.
OnSSLVerifyPeer
If verify certificate is enabled, in this event you can verify and decide whether to accept the server certificate.
OnSSLGetHandler
This event is raised before SSL handler is created, you can create here your own SSL Handler (needs to be inherited from TIdServerIOHandlerSSLBase or TIdIOHandlerSSLBase) and set the properties needed
OnSSLAfterCreateHandler
If no custom SSL object has been created, it creates by default using OpenSSL handler. You can access to SSL Handler properties and modify if needed