Documentation

ApiClient extends Client
in package

Description of ApiClient.

Tags
author

vitex

Table of Contents

Properties

$mockMode  : bool
Use mocking for api calls ?
$pSUIPAddress  : string
the end IP address of the client application (no server) in IPv4 or IPv6 format. If the bank client (your user) uses a browser by which he accesses your server app, we need to know the IP address of his browser.
$xIBMClientId  : string
ClientID obtained from Developer Portal - when you registered your app with us.
$certFilePath  : string
Path to the certificate file used for mTLS authentication.
$certFingerprint  : string|null
Cached certificate fingerprint for rate limiting.
$rateLimiter  : RateLimiter

Methods

__construct()  : mixed
Initialize the API client with configuration, certificate validation, and a rate limiter.
checkCertificate()  : bool
checkCertificatePassword()  : bool
checkCertificatePresence()  : bool
Try to check certificate readibilty.
getCertificateSerialNumber()  : string
Calculate and return the SHA1 fingerprint of the certificate used for mTLS.
getMockMode()  : bool
Use mocking uri for api calls ?
getpSUIPAddress()  : string
Keep user public IP here.
getPublicIP()  : string
Obtain Your current Public IP.
getXIBMClientId()  : string
ClientID obtained from Developer Portal.
getxRequestId()  : string
Produce a short request identifier used for diagnostics and testing.
send()  : ResponseInterface
Send an HTTP request while enforcing and updating client rate limits.
sourceString()  : string
Source Identifier.
sendAllowingErrorStatus()  : ResponseInterface
Send a request via Guzzle and return the response even when its status code represents an HTTP error.
updateRateLimitsFromResponse()  : void
Update rate limits from API response headers.

Properties

$mockMode

Use mocking for api calls ?

protected bool $mockMode = false

$pSUIPAddress

the end IP address of the client application (no server) in IPv4 or IPv6 format. If the bank client (your user) uses a browser by which he accesses your server app, we need to know the IP address of his browser.

protected string $pSUIPAddress = ''

Always provide the closest IP address to the real end-user possible. (optional).

$xIBMClientId

ClientID obtained from Developer Portal - when you registered your app with us.

protected string $xIBMClientId = ''

$certFilePath

Path to the certificate file used for mTLS authentication.

private string $certFilePath = ''

$certFingerprint

Cached certificate fingerprint for rate limiting.

private string|null $certFingerprint = null

Methods

__construct()

Initialize the API client with configuration, certificate validation, and a rate limiter.

public __construct([array<string|int, mixed> $config = [] ]) : mixed

Accepted $config keys:

  • 'clientid': client ID from the Developer Portal.
  • 'cert': array with [pathToP12, password]; when omitted, CERT_FILE and CERT_PASS configuration values are used.
  • 'clientpubip': client public IP (nearest to the end user).
  • 'mocking': bool to enable mock endpoints.
  • 'debug': debug flag.
Parameters
$config : array<string|int, mixed> = []

client configuration

  • 'clientid': client ID from Developer Portal
  • 'cert': [path, password]
  • 'clientpubip': client public IP
  • 'mocking': bool
  • 'debug': bool
  • 'rate_limit_store': RateLimitStoreInterface instance (optional)
  • 'rate_limit_wait': bool - wait when limited (default true)
Tags
throws
Exception

if certificate file path (CERT_FILE) is not provided

Exception

if certificate password (CERT_PASS) is not provided

checkCertificate()

public static checkCertificate(string $certFile, string $password) : bool
Parameters
$certFile : string
$password : string
Return values
bool

checkCertificatePassword()

public static checkCertificatePassword(string $certFile, string $password) : bool
Parameters
$certFile : string
$password : string
Return values
bool

checkCertificatePresence()

Try to check certificate readibilty.

public static checkCertificatePresence(string $certFile[, bool $die = false ]) : bool
Parameters
$certFile : string

path to certificate

$die : bool = false

throw exception or return false ?

Tags
throws
Exception
  • Certificate file not found
Return values
bool —

certificate file

getCertificateSerialNumber()

Calculate and return the SHA1 fingerprint of the certificate used for mTLS.

public getCertificateSerialNumber() : string

This fingerprint is used as the client identifier for rate limiting, as rate limits in the API are tied to the certificate, not to X-IBM-Client-Id.

Tags
throws
Exception

if unable to read or parse the certificate

Return values
string —

SHA1 fingerprint of the certificate in lowercase hex format

getMockMode()

Use mocking uri for api calls ?

public getMockMode() : bool
Return values
bool

getpSUIPAddress()

Keep user public IP here.

public getpSUIPAddress() : string
Return values
string

getPublicIP()

Obtain Your current Public IP.

public static getPublicIP() : string

since version 0.1 - Do not use in production Environment!

Return values
string

getXIBMClientId()

ClientID obtained from Developer Portal.

public getXIBMClientId() : string
Return values
string

getxRequestId()

Produce a short request identifier used for diagnostics and testing.

public static getxRequestId() : string

since version 0.1 — Do not use in production environments.

Return values
string —

the generated request identifier composed from a source token and the current timestamp, truncated to at most 59 characters

send()

Send an HTTP request while enforcing and updating client rate limits.

public send(RequestInterface $request[, array<string|int, mixed> $options = [] ]) : ResponseInterface

Rate limits are enforced per certificate (not per X-IBM-Client-Id). The certificate fingerprint is used as the client identifier, and the whole check-send-update cycle is serialized (via an exclusive file lock) across concurrent processes sharing that certificate, so parallel tasks (e.g. one per bank account under the same company certificate) can't race past the rate limiter's stale in-store counters and all land in the same request window.

Parameters
$request : RequestInterface

the HTTP request to send

$options : array<string|int, mixed> = []

Request options to apply to the transfer. See \GuzzleHttp\RequestOptions.

Tags
throws
GuzzleException
RateLimitExceededException

if the client is rate limited and wait mode is disabled

Return values
ResponseInterface —

the HTTP response

sourceString()

Source Identifier.

public static sourceString() : string

since version 0.1 - Do not use in production Environment!

Return values
string

sendAllowingErrorStatus()

Send a request via Guzzle and return the response even when its status code represents an HTTP error.

private sendAllowingErrorStatus(RequestInterface $request, array<string|int, mixed> $options) : ResponseInterface

By default Guzzle throws a RequestException (e.g. ClientException for 4xx, ServerException for 5xx) before the caller ever sees the response. That would bypass the 429 handling and rate-limit-header bookkeeping in send(), so here the response is recovered from the exception instead of letting it propagate.

Parameters
$request : RequestInterface
$options : array<string|int, mixed>
Tags
throws
GuzzleException

if the request failed without producing a response (e.g. connection error)

Return values
ResponseInterface

updateRateLimitsFromResponse()

Update rate limits from API response headers.

private updateRateLimitsFromResponse(ResponseInterface $response) : void

Uses the certificate fingerprint as the client identifier for storing rate limits.

Parameters
$response : ResponseInterface

the HTTP response containing rate limit headers

On this page

Search results