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.


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 value in the Address column of the table showing the addresses is a link, and the address can be updated in the popup window that opens when this link is clicked.


Adding a New Address

A new address can be added from the window that opens when the (plus) button in the right most column's header 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

An address is deleted when the (minus) icon on the row of the address is clicked.

API Proxy must have at least one address to be able to route the requests. Therefore, the delete icon is not active for the last address.

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.

In case the versions of the Backend API addresses given in SOAP Services are different (such as SOAP 1.1 and SOAP 1.2), the "content-type" header of the request message and the "namespace" value in the message body are changed according to the version of the address to which the message will be sent.

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.

Connection 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.

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.

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 image containing the Circuit Breaker settings is given below:

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 image containing the Client Flow Banner settings is given below:


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.

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 image containing the Proxy Server settings is given below:


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.


Changes made in the Routing tab are not saved until the Save Changes button in the upper right corner of the API Proxy interface is clicked. When the changes are saved, the Redeploy Required button for API Proxy becomes active. Addresses or other changes are not reflected to clients until this button is clicked.

Some Important Points

  • 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.