After API Proxy receives the messages from the client and executes the policies, if any, it forwards the message to the Backend API. The Routing tab is the tab where this process is configured.

The picture below shows the Routing Tab:

Management of Backend API Addresses

While creating the API Proxy, the access address of the Backend API can be obtained in different ways:

  • If an API Definition File is used, the address or at least one of the addresses in this file is selected by the user.
  • If API Proxy is created with the Empty API option (for example, for a Backend API developed with a code-first approach), the address of the Backend API is entered by the user.
  • If API Proxy is created for an API created with API Creator (DB-2-API, Mock API or Script-2-API), the Backend API address is not requested, it is managed by Apinizer. The Routing Tab is closed for this type of API.

The address information obtained during the creation phase can be changed later, new addresses can be added or existing ones can be deleted. For this, the Addresses section of the Forwarding Tab is used.


Updating an Address

The address can be updated in the window that opens when the Configure button in the Address column of the table showing the addresses is clicked.


If the type of API Proxy is SOAP; SOAP Type information added/edited in this section is reflected in the port information in WSDL.

Adding a New Address

A new address can be added from the window that opens when the (plus) button in the column header area at the far right of the window opened with the Configure button is clicked.

Conditional Routing

The Condition section in the window that opens for adding or updating an address allows users to define the conditions required for the messages to be sent to this address. Thus, for example, requests that contain a special header or parameter value can be directed to only a specific one among all the addresses.

An example of a practical use case would be to forward requests with the "test=true" parameter to the test server, and requests without this parameter to the production server. Another scenario can be considered as routing requests to servers in different regions based on clients' IP values.

Deleting an Address

The address is deleted by selecting the Remove option from the drop down menu at the end of the line of the address to be deleted.

API Proxy must have at least one address to be able to route the requests. Therefore, after the last address is deleted, the save button becomes inactive and does not allow saving.

Load Balancing 

In case the load on the Backend API increases, it is possible to distribute the load by installing the same API/Web Service on another server. In order for the new server to be accessible to the clients, no network settings are required, it is sufficient to add it to the Addresses section on Apinizer. Apinizer distributes the load among these addresses if more than one address is defined for a Backend API.


Users can select the algorithm to be used for load balancing.

AlgorithmDescription
Round RobinRequest messages are sent to the addresses in the list in order. When the end of the list is reached, it returns to the beginning of the list and the same cycle continues.
LRU (Least Recently Used)Request messages are redirected to the server which is unused for the longest time among all the servers in the list.
WeightedUser assigns weights to the addresses. Considering these weights, requests are directed to the servers in order. For example; if one of the two addresses has a weight of 1 and the other a weight of 2, 1 request is forwarded to the address with a weight of 1, while 2 requests are forwarded to the address with a weight of 2.
RandomRequest messages are forwarded to randomly selected addresses.
Load Balancing Type

Apinizer can be configured to run multiple Workers in each Environment. Thus, the load is distributed among the API Proxies on the Workers in that Environment. In this case, the API Proxies on each Worker must know the Backend API addresses. 

The Load Balancing Type parameter determines how to keep the information of number of visits or the time of the last visit to each address is made for load balancing. If Single is selected, each Worker operates the load balancing addresses independently from other Workers. If Distributed is selected, Workers load balance over the same and a single access data using a distributed cache. Accordingly, while Single works faster, Distributed guarantees that the load balancing algorithm is operated strictly.


Timeouts 

If a request cannot be sent to the Backend API for a certain period of time, or if there is no response within a certain period of time, the request must be terminated and the error reported or failover must be performed.

There are two different timeout parameters that can be used for this purpose.

Connect Timeout

It is the maximum time to wait to be able to connect to the Backend API and send the request message. Its unit is second. If the Backend API is not accessible during this period;

  • According to the values of Retry Count and Failover Retry Count parameters, new requests can be sent to the same address or to other addresses in the list, if any,
  • An error may be returned to the client.

Read Timeout

It is the maximum time to wait to receive the response message from the Backend API. Its unit is second. If no response is received from the Backend API during this period;

  • According to the values of Retry Count and Failover Retry Count parameters, new requests can be sent to the same address or to other addresses in the list, if any,
  • An error may be returned to the client.

Connection Request Timeout 

The timeout used when requesting a connection from the connection manager. Its unit is milliseconds.

Failover

If the timeout period is exceeded or an error is returned from the Backend API, instead of immediately returning an error to the client, a request is sent to the same address or other addresses to ensure that the operation is successful.

Two different parameters are used for this:

Retry Count

If the request or expected response message times out or if an error is returned from the Backend API, the value of the Retry Count parameter is checked before returning the error message to the client. If this value is greater than 0, a request is sent back to the Backend API. This operation refreshes as much as the value of this parameter.

Failover Retry Count

If requests as much as the Retry Count parameter's value are sent to the Backend API, but still a timeout occurs or an error message is returned from the Backend API, the value of the Failover Retry Count parameter is checked. If this value is greater than 0, requests are sent to other Backend API addresses. Trying different addresses will be repeated as much as the value of this parameter. A single attempt is made for each new address, and if successful results are not obtained, the next address is passed. If the number of addresses defined is less than the value of the Failover Retry Count parameter, the process is terminated and an error is returned to the client because there is no new address to try.

Keeping the Original Error Message of the Backend API

With the configuration made in the XML/JSON Error Response Template section of the Overview Tab for an API Proxy, templates can be defined that determine how an error message is returned to the client in error situations. These error templates allow for customization by handling errors related to the applied policies. However, sometimes the error message returned from the Backend API may contain meaningful data for the client and therefore it is desirable to return this message to the client as it is. In such a case, the box of the Ignore Error Response Template In Case Of Error On Backend API parameter is checked. When this parameter is checked, the templates defined in the Error Response Template section will not be processed only if an incorrect message is returned from the Backend API. However, these templates will be used, for example, for error responses resulting from any policy.

Error Handling 

Here is used to determine whether the result returned from the Backend address will be evaluated as "Success" or "Failure".

The picture below shows the error handling type and condition:


There are three options for Error Handling; default settings, advanced settings and status code list:

  • If default settings are selected, then the status of the response message is checked to see if "HTTP status code >= 400". If the condition is met, the status of the message is evaluated as "Failure".
  • If advanced settings are selected, then it is checked whether the condition specified on the response message is met. If the condition is met, the status of the message is evaluated as "Failure". For example; The condition can be written as "(HTTP status code = 500 or HTTP status code = 501) and (message body contains "error") ..etc".
  • If the status code list is selected, then the HTTP status code of the response message is checked to see if it is included in the specified list. If the condition is met, the status of the message is evaluated as "Failure".


Policies in the response pipeline are not executed if response evaluation result is "failure".


Connection Pool Management

The picture below shows the Connection Pool Management settings:


Fields used for Connection Pool Management configuration are shown below.

Field

Description

Connection Pool Management Type

Connection Pool Management options:

  • General: The existing General Connection Pool settings for the Environment are applied.
  • Customize: This option is used to create API Proxy specific Connection Pool.
  • None: If the None option is selected, the Connection Pool is not created.


Fix SOAP Action and Namespace

With this option active in SOAP and Rest2Soap services, the correction of SOAP actions and namespaces is performed based on the WSDL by default.

If the setting is disabled, no change is made to the request sent by the client.

The picture below shows the Fix SOAP Action and Namespace setting:

Hop-by-hop headers to delete

The picture below shows the Hop-by-hop headers to delete settings:

Send User Agent to Backend

The picture below shows the Send User Agent to Backend settings:

Circuit Breaker

Requests from clients to APIs may fail due to slow network connections, timeouts, and temporary errors such as resource overload or temporary disablement. The causes of such errors will normally disappear in a short time. However, the servers must be given time to eliminate the causes of the errors. Circuit Breaker, a microservice architecture pattern, serves this purpose. 

The Circuit Breaker monitors the available endpoints in a load-balancing system, stopping access to the relevant endpoint for a while in case of any abnormality in the endpoint responses.

The picture below shows the Circuit Breaker configuration settings:

In order for the Circuit Breaker to be used, at least two addresses must be defined for the Backend API in the addresses section.

Parameters used for Circuit Breaker configuration are shown below.

Field

Description

Enable Circuit Breaker

It enables the configuration parameters to be entered by activating the Circuit Breaker.

Error Window

Specifies the time frame that Backend API addresses are monitored for errors. Its unit is second.

Error Threshold Value

Indicates how many errors will be accepted within the monitored period. When the error threshold is exceeded, no new request will be sent to that Backend API address for the period specified by the Sleep Window parameter.

Error Threshold Type

Specifies how the error count will be handled. Given the definitions below,

  • Number of errors during the Error Window: NoE
  • Total number of messages received during the Error Window: NoM
  • Error Threshold Value: ETV

sending messages to the API will be stopped 

  • if COUNT option is selected and NoE >= ETV 
  • if PERCENT option is selected and NoE >= (NoM * ETV) / 100

Sleep Window

Indicates how long no new request will be sent to the Backend API address where an error is received and the Error Threshold Value is exceeded. Incoming requests during this period are forwarded to other address(es). At the end of the period, it will start sending requests to this address again.

Enable Half Open

If this option is checked, after the time specified by the Sleep Window parameter, 1 request is sent to the relevant address, and it is checked whether the problem at that address has disappeared. If the returned result is incorrect, this address will be closed to new requests again during the Sleep Window period.

If this option is not checked, the values of the relevant address will be reset after the time specified with the Sleep Window parameter and monitoring will restart for this address during the Error Window.


Circuit Breaker is applied separately for each address. When the Error Threshold Value is exceeded, the circuit breaker only blocks access to the endpoint at the relevant address.

Client Flow Banner

It is not expected for a client to receive repeated errors from the Backend API. If such a situation occurs, it is most likely a software error or need for an update. Access to the Backend API of clients that continue to send requests over and over despite receiving errors can be restricted with the Client Flow Banner. This prevents other clients from being adversely affected by this situation.

The picture below shows the Client Flow Banner configuration settings:


The parameters used for the Client Flow Banner configuration are shown below.

Field

Description

Enable Client Flow Banner

It enables the configuration parameters to be entered by activating the Client Flow Banner.

Variable for Client Identity

The location of the data to be received from the message to find out the identity of the client.

Error Window

Specifies the time frame that clients are monitored for errors. Its unit is second.

Error Threshold Value

Indicates how many errors will be accepted within the monitored period. When the error threshold is exceeded, no new request will be sent to that Backend API address for the period specified by the Sleep Window parameter.

Error Threshold Type

Specifies how the error count will be handled. Given the definitions below,

  • Number of errors during the Error Window: NoE
  • Total number of messages received during the Error Window: NoM
  • Error Threshold Value: ETV

sending messages to the API will be stopped 

  • if COUNT option is selected and NoE >= ETV 
  • if PERCENT option is selected and NoE >= (NoM * ETV) / 100

Banning Window

Specifies how long a new request will not be accepted from the client. Its unit is second.

Download

If the type of API Proxy is Reverse Proxy, the Download option can be activated.

Which response message is downloadable is determined by the Content-Type header value in the return value. If the values here are included in the list on the Byte Array Content Types page in the system settings, it is decided that the returned value is downloadable.


If the download option is activated;

  • If the response content type of the accessed endpoint is downloadable content, it is downloaded as a file.
  • If the response content type of the accessed endpoint is not downloadable content, the request is not affected, flow continues.

If the download option is not activated;

  • if the response content type of the accessed endpoint is downloadable content, the content is Base64 encoded and returned as a String.
  • If the response content type of the accessed endpoint is not downloadable content, the request is not affected, flow continues.

Proxy Server

In some cases, the Backend API address may be behind a proxy server. Proxy server settings required in such a scenario are made in the Proxy Server section of the Routing tab.

The picture below shows the Proxy Server configuration settings:


Parameters used for Proxy Server configuration are shown below.

Field

Description

Use Proxy Server

It enables the configuration parameters to be entered by activating the Proxy Server settings.

Get information from request header


The "X-Proxy-Host" and "X-Proxy-Port" headers are used for the proxy server, and the "Proxy-Authorization" header is used if authorization is required.

The "Proxy-Authorization" header is used to authorize the user used to connect to the proxy server. It is created by combining the username and password with a colon and encoding it with Base64.

HostThe host name or IP of the proxy server.
PortThe port of the proxy server

Proxy Server requires Authorization

It is activated if authorization is required for proxy server access.

Username

The username that has access to the proxy server.

Password

The password for the given username.


mTLS Settings

Selected mTLS settings are optionally applied when this setting is enabled.

Thus, the Apinizer client, which will send from Apinizer to the target service, validates the target service's certificate and indicates that it has a certificate and must be verified by the target service.

The target service also verifies the client's certificate, thus establishing a secure communication with the client.

The picture below shows the mTLS configuration settings:


Parameters used for mTLS configuration are shown below.

Field

Description

Keystore

Keystore is selected. If it is not defined before, a new one can be created by pressing the + button on the side.

TruststoreTruststore is selected. If it is not defined before, a new one can be created by pressing the + button on the side.

Supported Protocol List

Supported protocols are selected. Options:

  • TLSv1.3
  • TLSv1.2
  • TLSv1.1
  • TLSv1
  • SSLv3

Hostname Verifier Type

The Noop Hostname Verifier disables the hostname verification in SSL/TLS connections, which can be a security risk. It's important to verify the hostname of the server to prevent man-in-the-middle (MITM) attacks, where an attacker can intercept the SSL/TLS communication and impersonate the server.

Instead of using Noop Hostname Verifier , you can use one of the following hostname verification implementations provided by the Apache HttpComponents client framework:

  1. Default Hostname Verifier: This implementation performs the standard hostname verification based on the rules defined in RFC 2818 and RFC 6125. It checks the common name (CN) and subject alternative names (SANs) of the server certificate to ensure that the hostname matches.

  2. Strict Hostname Verifier: This implementation performs a stricter hostname verification than the Default Hostname Verifier. It requires an exact match between the hostname and the CN or SANs of the server certificate. It also checks that the hostname is a fully qualified domain name (FQDN), and not an IP address or a wildcard domain name.

  3. Browser Compat Hostname Verifier: This implementation performs a relaxed hostname verification based on the rules used by popular web browsers. It allows a wildcard domain name to match any subdomain of the domain name, and ignores the case sensitivity of the hostname.

When mTLS settings are enabled, the existing "http connection pool" in the routing, whose values are specified in the environment settings, is disabled.


NTLM Settings 

Selected NTLM settings are optionally applied when this setting is enabled.

The picture below shows the NTLM configuration settings:


Parameters used for NTLM configuration are shown below.

Field

Description

Domain

It is the domain information related to the NTLM setting.
UsernameIt is the username information related to the NTLM setting.

Password

It is the password information related to the NTLM setting.

Workstation

It is the workstation information related to the NTLM setting.

Customize Error Messages

When an error is thrown from the policies, Apinizer sends the default error message to the user if it is not customized. Click to learn more about customizing error messages.

Some Important Points:

  • When the changes made in the Routing tab are saved, the Redeploy Required button for API Proxy becomes active. Changes made until this button is clicked are not reflected in the gates.
  • The following headers from the client are not sent to the Backend API
    • Content-Length
    • Host
    • User-Agent
    • Connection
    • Keep-Alive
    • Proxy-Authenticate
    • Proxy-Authorization
    • TE
    • Trailers
    • Upgrade
  • If the Content-Encoding and Transfer-Encoding headers from the client contain "gzip" value, the message body is gzipped and sent to the Backend API
  • If the Content-Encoding and Transfer-Encoding headers from the client contain "deflate" value, the message body is deflated and sent to the Backend API.
  • If the Content-Encoding header from the Client, or Content-Encoding or Transfer-Encoding response headers from the Backend API contains "gzip" value, the response body is gzipped and sent to the Client.
  • If the Accept-Encoding header from the Client, or Accept-Encoding, Content-Encoding or Transfer-Encoding response headers from the Backend API contains "deflate" value, the response body is deflated and sent to the Client.
  • The Gzip or Deflate process is applied just before the message is delivered to the client, after all response policies have been executed. Thus, the operation of the policies is not affected.