This tab contains general settings related to the selected API Proxy.

The picture below shows the Overview Tab:


If the relevant API Proxy is included in a Group, click the API Proxy Group Enabled link to go to the Group screen to which the API Proxy belongs.


The settings are divided into various sections.

Definition Section

It is the section where API Proxy-specific definition information such as name, description, access address, categories are found.

The picture below shows the Definition section :


The Definition fields are shown in the table below.

Field

Description

NameIt is the name given to the API Proxy by the user. It should be unique across the project.

Description

It is an optional description of the API Proxy.
UsageIt is the section where the way of using API Proxy as Producer, Consumer or Producer and Consumer is specified.

Relative Path

Relative Path is a part of the access URL of this API Proxy.

The address of the API Proxy is used to direct incoming requests to the appropriate API Proxy. For this, a unique address is created using the Relative Path of each deployed API Proxy, as in the example below:

Let the address of the server where Apinizer is running is: https://demo.apinizer.com

Let the Relative Path is /petstoreProxy. 

Let the Access URL of the Environment that the API Proxy is deployed to is /apigateway.

Let the endpoint that is to be accessed is /findByStatus.

The URL for this endpoint will be:

https://demo.apinizer.com/apigateway/petstoreProxy/findByStatus.

Relative Path must be unqiue across the Project.

If the Enable Relative Path value is enabled for the Project while making the Project settings, the Relative Path defined for the Project will be a read-only prefix for the Relative Paths of all API Proxies that will be created in this project.

Category List

Categories can be created to facilitate the management of API Proxies. The category list is used to identify which categories the API Proxy belongs to.


API Proxy Key Section 

It is the section where access keys of API Proxy are managed. Access keys are used for OAuth2 Authentication Policy.

Client Id and Client Secret values are created automatically and the user can request new ones to be created. If any of the keys are regenerated for an deployed API Proxy, the API Proxy must be redeployed for the keys to be valid.


Deployment Section 

The deployment section is the section where the API Proxy is deployed, and its addresses for the Environments it is deployed to are displayed. An API Proxy can be deployed to multiple Environments concurrently.

If an API Proxy Group is created from API Proxy, information about that group is also displayed in this field.


The Deployment fields are shown in the table below.

Field

Description

Status

It is the status of the API Proxy in the relevant Environment.

Environment

It is the Environment information to which the API Proxy is deployed.

URL

It is the access address of the API Proxy. It is automatically generated using the Relative Path and the access URL of the Environment it is deployed to.

Specs

Definition files of API Proxy. For each API Proxy, definition files are generated in Swagger 2.x and OpenAPI 3.0.x formats. If the type of API Proxy is SOAP, WSDL and XSD definition files will also be generated. When the Show Specs link is clicked for any Environment, API Definition Files of the API Proxy for that environment are displayed.


When the Show Spec button is clicked, the dialog showing API Proxy definitions in different types and formats is given below:


If the relevant API Proxy is included in a Group and the option to Disable Direct Access to API Proxies is selected on the API Proxy Group screen, a warning box will appear in this section.

Accessing API Proxy Definition Files

The contents of the definition files are displayed as shown in the figure above when the Show Specs link is clicked and they can be copied from here. However, this method is for users such as API Developers, API Testers which works on the Apinizer platform. Clients (API Consumers) cannot access these interfaces.

Clients can use the URL of the API Proxies to access the definition files as follows:

Let the access URL of an API Proxy on Production Environment is https://demo.apinizer.com/apigateway/petstoreProxy.

Then, URLs below can be used to access the definition files:

Swagger 2.x (JSON)

  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger
  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger&format=json
  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger.json

Swagger 2.x (YAML)

  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger&format=yaml
  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger.yaml

OpenAPI 3.x (JSON)

  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi
  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi&format=json
  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi.json

OpenAPI 3.x (YAML)

  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi&format=yaml
  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi.yaml

WSDL (if the API Proxy is SOAP)

  • https://demo.apinizer.com/apigateway/calc?wsdl


Settings Section

It is the section that CORS, Cache, Error Response Templates, Forwarded IP Header Parameters and Log settings of the API Proxy are configured.


If the relevant API Proxy is included in a Group and the Apply Settings to Related API Proxies option is selected on the API Proxy Group screen, the settings in this section cannot be changed. The group's settings apply.

CORS 

CORS (Cross-Origin Resource Sharing) can be configured in this subsection.


The CORS fields are shown in the table below.

Field

Description

Activate CORS

Enables/disables CORS settings.

Request Headers


Origin

It contains the origin (domain, protocol, port) information from which the preflight request is sent.

Access-Control-Request-MethodThe HTTP method to be sent in the original request is specified.
Access-Control-Request-HeadersThe HTTP headers to be sent in the original request is specified.
Access-Control-Max-Age

It is given in seconds how long the response of the preflight request will remain in the cache without sending another preflight request. 

Access-Control-Allow-Headers

Header values that API Proxy allows for access are entered. If Access-Control-Request-Headers is specified in the preflight request, this header is placed on the response. It contains information about which HTTP headers can be used in the original request.

Access-Control-Allow-Methods

It contains the HTTP methods that are allowed when accessing the server. The methods that API Proxy allows for access are selected from the list by ticking:

  • GET
  • POST
  • PUT
  • HEAD
  • OPTIONS
  • DELETE
  • PATCH
  • TRACE
  • ALL

Response Headers

Access-Control-Allow-OriginOrigin values allowed by API Proxy are entered. If * is entered in this field, all origins can send requests.
Access-Control-Allow-CredentialsIn the original request, the value of whether the credentials are present is entered.
Access-Control-Expose-HeadersOther headers that clients can access are entered.

Cache

By caching the responses returned from the API Proxy, requests of the client can be answered from the cache without sending them to the Backend API. This is the section where the settings for this are managed.


The Cache fields are shown in the table below.

Field

Description

Activate Cache

Enables/disables cache.
CapacityMaximum number of the responses to be cached.
TTLThe length of time the cached response will remain in the cache. It is given in seconds.

Invalidation Requires Authn

Selected if authorization is required to invalidate the cache.

Handling Action

If authorization is required to invalidate the cache, the action to take for unauthorized requests is selected:

  • CONTINUE
  • STOP

Cache Null Value

Checked if null values are also to be cached.


XML/JSON Error Response Template 

It is used to prepare response templates that will be used when any error is returned from the API Proxy to the client.

When any template is activated, the default template is displayed and can be customized if desired.

The XML/JSON Error Response Template fields are shown in the table below.

FieldDescription

Activate XML Error Response Template

Enables/disables the XML Error Response Template 

Permit Special Chars in Response Message

Special characters that may be present in the error message of the response can corrupt the XML message structure. Determines whether these are allowed or not.
XML The error template of XML type can be edited in this field.

Content Type

The content type of the response to be returned.

Activate JSON Error Response Template

Enables/disables the JSON Error Response Template.

Permit Special Chars in Response Message

Special characters that may be present in the error message of the response can corrupt the JSON message structure. Determines whether these are allowed or not.
JSONThe JSON type error template can be edited in this field.
Content TypeThe content type of the response to be returned.


Within the response templates, the values in the form #...# are used as placeholders to put the relevant part of the error message. Placeholders and their descriptions are in the following table:

PlaceholderDescription
#CORRELATIONID#Apinizer creates a unique key for each incoming request so that the request can be tracked throughout the flow. By using this key, for example, it becomes possible to follow the log records of the applications by associating them with the log records on Apinizer.
#FAULTCODE#Specifies where to put the error code to be returned to the client in the response message.
#FAULTMESSAGE#Specifies where to place the error message returned to the client in the response message.
#FAULTMESSAGE_FIRSTLINE#The first line or first 150 characters of the error message to be returned to the client are taken and put in the response message.
#FAULTSTATUSCODE#Specifies where to put the HTTP Status Code returned to the client in the response message.
#RESPONSEFROMAPI#If there is a response returned from the Backend API, it determines where the response will be placed in the response message to be returned to the client.
#RESPONSEFROMAPI_FIRSTLINE#The first line or first 150 characters of a response returned from the Backend API are taken and put into the response message to be returned to the client.


Both templates can be activated if desired. If both templates are active, which one will be used is decided according to the following criteria:

  • If the value of the Content-Type header specifies the JSON format, the JSON Error Response Template is used.
  • If the Content-Type header is empty and the API Proxy's type is REST, the JSON Error Response Template is used.
  • If these are not valid, the XML Error Response Template is used.

If both templates are not activated or the cause of the error is API Proxy not found (address may be wrong, API Proxy may not be deployed), following response returns with text/plain;charset=utf-8 header:

[#CORRELATIONID#],[#FAULTCODE#],[#FAULTMESSAGE#],[#FAULTSTATUSCODE#],[#RESPONSEFROMAPI#]


If the "Ignore Error Response Template In Case Of Error On Backend API" option is selected in the Routing tab of the API Proxy, the templates defined in this section are not used, and the error response of the Backend API is sent to the client as it is.

Forwarded IP Header Parameters

If the API Proxy is behind a Load Balancer or Proxy Server, the IP value of the client cannot be known by the API Proxy or Backend API, since the request from the client will be directed to the API Proxy by this layer. Therefore, Load Balancers or Proxy Servers can transmit the original client's IP with a header. The Forwarded IP Header Parameters setting ensures that the client IP is accessible by the API Proxy and Backend API by specifying the name of this header, which can vary by software/hardware.


The Forwarded IP Header Parameter fields are shown in the table below.

Field

Description

Activate Forwarded IP Header Parameter

Enables/disables the Forwarded IP Header Parameter settings.

Forwarded IP Header Parameter

It is the name of the header in which the IP is forwarded.

IP to Use

If the request passed through more than one proxy, more than one IP address will accumulate in the XFF value. In this case, which address will be taken is decided by XFF Order. If there is more than one address and XFF Order is empty, the first address is used by default. If there is more than one address and XFF Order is full and there are values in the desired order, this address is used. If there is more than one address and XFF Order is full but there is no value in the desired order, the last address is used by default. Only the following options are suitable for the IP to be used:

  • First
  • Second
  • Third
  • Fourth
  • Fifth
  • Last 

Log Settings

Requests and response messages to API Proxy are logged to Elasticsearch database. Log records contain two types of data:

  • The first of these is metric data. Storing metric data is not optional.
  • The second is the content that consists header, parameter and body fields of the request and response messages in these 4 regions: Client → API Proxy, API Proxy → Backend API, Backend API → API Proxy, API Proxy → Client. Which of these fields will be included in the log records can be determined according to the need or based on the resource consumption of the log server.

By default, log fields in all message zones of the project are active. Although all log fields are active by default, it is recommended to disable Body fields so that the log data does not overgrow, especially in Production Environments.


The Log Settings fields are shown in the table below.

FieldDescription

Enable All Logs

Enables logging for all regions.

Disable All Logs

Disables logging for all regions.
HeaderEnables logging the Header values for the relevant region.
BodyEnables logging the content of the Body for the relevant region.
ParameterEnables logging the Parameter values for the relevant region.


In the Log Settings section, log settings are managed for the relevant API Proxy only. Logging can be disabled for Environment(s) under the Project Settings menu. In this case, no logs are kept even if the log settings for API Proxy are enabled.

This tab contains general settings related to the selected API Proxy.

The picture below shows the Overview Tab:


If the relevant API Proxy is included in a Group, click the API Proxy Group Enabled link to go to the Group screen to which the API Proxy belongs.


The settings are divided into various sections.

Definition Section

It is the section where API Proxy-specific definition information such as name, description, access address, categories are found.

The picture below shows the Definition section :


The Definition fields are shown in the table below.

Field

Description

NameIt is the name given to the API Proxy by the user. It should be unique across the project.

Description

It is an optional description of the API Proxy.
UsageIt is the section where the way of using API Proxy as Producer, Consumer or Producer and Consumer is specified.

Relative Path

Relative Path is a part of the access URL of this API Proxy.

The address of the API Proxy is used to direct incoming requests to the appropriate API Proxy. For this, a unique address is created using the Relative Path of each deployed API Proxy, as in the example below:

Let the address of the server where Apinizer is running is: https://demo.apinizer.com

Let the Relative Path is /petstoreProxy. 

Let the Access URL of the Environment that the API Proxy is deployed to is /apigateway.

Let the endpoint that is to be accessed is /findByStatus.

The URL for this endpoint will be:

https://demo.apinizer.com/apigateway/petstoreProxy/findByStatus.

Relative Path must be unqiue across the Project.

If the Enable Relative Path value is enabled for the Project while making the Project settings, the Relative Path defined for the Project will be a read-only prefix for the Relative Paths of all API Proxies that will be created in this project.

Category List

Categories can be created to facilitate the management of API Proxies. The category list is used to identify which categories the API Proxy belongs to.


API Proxy Key Section 

It is the section where access keys of API Proxy are managed. Access keys are used for OAuth2 Authentication Policy.

Client Id and Client Secret values are created automatically and the user can request new ones to be created. If any of the keys are regenerated for an deployed API Proxy, the API Proxy must be redeployed for the keys to be valid.


Deployment Section

The deployment section is the section where the API Proxy is deployed, and its addresses for the Environments it is deployed to are displayed. An API Proxy can be deployed to multiple Environments concurrently.

If an API Proxy Group is created from API Proxy, information about that group is also displayed in this field.


The Deployment fields are shown in the table below.

Field

Description

Status

It is the status of the API Proxy in the relevant Environment.

Environment

It is the Environment information to which the API Proxy is deployed.

URL

It is the access address of the API Proxy. It is automatically generated using the Relative Path and the access URL of the Environment it is deployed to.

Specs

Definition files of API Proxy. For each API Proxy, definition files are generated in Swagger 2.x and OpenAPI 3.0.x formats. If the type of API Proxy is SOAP, WSDL and XSD definition files will also be generated. When the Show Specs link is clicked for any Environment, API Definition Files of the API Proxy for that environment are displayed.


When the Show Spec button is clicked, the dialog showing API Proxy definitions in different types and formats is given below:


If the relevant API Proxy is included in a Group and the option to Disable Direct Access to API Proxies is selected on the API Proxy Group screen, a warning box will appear in this section.

Accessing API Proxy Definition Files

The contents of the definition files are displayed as shown in the figure above when the Show Specs link is clicked and they can be copied from here. However, this method is for users such as API Developers, API Testers which works on the Apinizer platform. Clients (API Consumers) cannot access these interfaces.

Clients can use the URL of the API Proxies to access the definition files as follows:

Let the access URL of an API Proxy on Production Environment is https://demo.apinizer.com/apigateway/petstoreProxy.

Then, URLs below can be used to access the definition files:

Swagger 2.x (JSON)

  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger
  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger&format=json
  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger.json

Swagger 2.x (YAML)

  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger&format=yaml
  • https://demo.apinizer.com/apigateway/petstoreProxy?swagger.yaml

OpenAPI 3.x (JSON)

  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi
  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi&format=json
  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi.json

OpenAPI 3.x (YAML)

  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi&format=yaml
  • https://demo.apinizer.com/apigateway/petstoreProxy?openapi.yaml

WSDL (if the API Proxy is SOAP)

  • https://demo.apinizer.com/apigateway/calc?wsdl


Settings Section

It is the section that CORS, Cache, Error Response Templates, Forwarded IP Header Parameters and Log settings of the API Proxy are configured.


If the relevant API Proxy is included in a Group and the Apply Settings to Related API Proxies option is selected on the API Proxy Group screen, the settings in this section cannot be changed. The group's settings apply.

CORS 

CORS (Cross-Origin Resource Sharing) can be configured in this subsection.


The CORS fields are shown in the table below.

Field

Description

Activate CORS

Enables/disables CORS settings.

Request Headers


Origin

It contains the origin (domain, protocol, port) information from which the preflight request is sent.

Access-Control-Request-MethodThe HTTP method to be sent in the original request is specified.
Access-Control-Request-HeadersThe HTTP headers to be sent in the original request is specified.
Access-Control-Max-Age

It is given in seconds how long the response of the preflight request will remain in the cache without sending another preflight request. 

Access-Control-Allow-Headers

Header values that API Proxy allows for access are entered. If Access-Control-Request-Headers is specified in the preflight request, this header is placed on the response. It contains information about which HTTP headers can be used in the original request.

Access-Control-Allow-Methods

It contains the HTTP methods that are allowed when accessing the server. The methods that API Proxy allows for access are selected from the list by ticking:

  • GET
  • POST
  • PUT
  • HEAD
  • OPTIONS
  • DELETE
  • PATCH
  • TRACE
  • ALL

Response Headers

Access-Control-Allow-OriginOrigin values allowed by API Proxy are entered. If * is entered in this field, all origins can send requests.
Access-Control-Allow-CredentialsIn the original request, the value of whether the credentials are present is entered.
Access-Control-Expose-HeadersOther headers that clients can access are entered.

Cache

By caching the responses returned from the API Proxy, requests of the client can be answered from the cache without sending them to the Backend API. This is the section where the settings for this are managed.


The Cache fields are shown in the table below.

Field

Description

Activate Cache

Enables/disables cache.
CapacityMaximum number of the responses to be cached.
TTLThe length of time the cached response will remain in the cache. It is given in seconds.

Invalidation Requires Authn

Selected if authorization is required to invalidate the cache.

Handling Action

If authorization is required to invalidate the cache, the action to take for unauthorized requests is selected:

  • CONTINUE
  • STOP

Cache Null Value

Checked if null values are also to be cached.


XML/JSON Error Response Template

It is used to prepare response templates that will be used when any error is returned from the API Proxy to the client.

When any template is activated, the default template is displayed and can be customized if desired.

The XML/JSON Error Response Template fields are shown in the table below.

FieldDescription

Activate XML Error Response Template

Enables/disables the XML Error Response Template 

Permit Special Chars in Response Message

Special characters that may be present in the error message of the response can corrupt the XML message structure. Determines whether these are allowed or not.
XML The error template of XML type can be edited in this field.

Content Type

The content type of the response to be returned.

Activate JSON Error Response Template

Enables/disables the JSON Error Response Template.

Permit Special Chars in Response Message

Special characters that may be present in the error message of the response can corrupt the JSON message structure. Determines whether these are allowed or not.
JSONThe JSON type error template can be edited in this field.
Content TypeThe content type of the response to be returned.


Within the response templates, the values in the form #...# are used as placeholders to put the relevant part of the error message. Placeholders and their descriptions are in the following table:

PlaceholderDescription
#CORRELATIONID#Apinizer creates a unique key for each incoming request so that the request can be tracked throughout the flow. By using this key, for example, it becomes possible to follow the log records of the applications by associating them with the log records on Apinizer.
#FAULTCODE#Specifies where to put the error code to be returned to the client in the response message.
#FAULTMESSAGE#Specifies where to place the error message returned to the client in the response message.
#FAULTMESSAGE_FIRSTLINE#The first line or first 150 characters of the error message to be returned to the client are taken and put in the response message.
#FAULTSTATUSCODE#Specifies where to put the HTTP Status Code returned to the client in the response message.
#RESPONSEFROMAPI#If there is a response returned from the Backend API, it determines where the response will be placed in the response message to be returned to the client.
#RESPONSEFROMAPI_FIRSTLINE#The first line or first 150 characters of a response returned from the Backend API are taken and put into the response message to be returned to the client.


Both templates can be activated if desired. If both templates are active, which one will be used is decided according to the following criteria:

  • If the value of the Content-Type header specifies the JSON format, the JSON Error Response Template is used.
  • If the Content-Type header is empty and the API Proxy's type is REST, the JSON Error Response Template is used.
  • If these are not valid, the XML Error Response Template is used.

If both templates are not activated or the cause of the error is API Proxy not found (address may be wrong, API Proxy may not be deployed), following response returns with text/plain;charset=utf-8 header:

[#CORRELATIONID#],[#FAULTCODE#],[#FAULTMESSAGE#],[#FAULTSTATUSCODE#],[#RESPONSEFROMAPI#]


If the "Ignore Error Response Template In Case Of Error On Backend API" option is selected in the Routing tab of the API Proxy, the templates defined in this section are not used, and the error response of the Backend API is sent to the client as it is.

Forwarded IP Header Parameters

If the API Proxy is behind a Load Balancer or Proxy Server, the IP value of the client cannot be known by the API Proxy or Backend API, since the request from the client will be directed to the API Proxy by this layer. Therefore, Load Balancers or Proxy Servers can transmit the original client's IP with a header. The Forwarded IP Header Parameters setting ensures that the client IP is accessible by the API Proxy and Backend API by specifying the name of this header, which can vary by software/hardware.


The Forwarded IP Header Parameter fields are shown in the table below.

Field

Description

Activate Forwarded IP Header Parameter

Enables/disables the Forwarded IP Header Parameter settings.

Forwarded IP Header Parameter

It is the name of the header in which the IP is forwarded.

IP to Use

If the request passed through more than one proxy, more than one IP address will accumulate in the XFF value. In this case, which address will be taken is decided by XFF Order. If there is more than one address and XFF Order is empty, the first address is used by default. If there is more than one address and XFF Order is full and there are values in the desired order, this address is used. If there is more than one address and XFF Order is full but there is no value in the desired order, the last address is used by default. Only the following options are suitable for the IP to be used:

  • First
  • Second
  • Third
  • Fourth
  • Fifth
  • Last 

Log Settings

Requests and response messages to API Proxy are logged to Elasticsearch database. Log records contain two types of data:

  • The first of these is metric data. Storing metric data is not optional.
  • The second is the content that consists header, parameter and body fields of the request and response messages in these 4 regions: Client → API Proxy, API Proxy → Backend API, Backend API → API Proxy, API Proxy → Client. Which of these fields will be included in the log records can be determined according to the need or based on the resource consumption of the log server.

By default, log fields in all message zones of the project are active. Although all log fields are active by default, it is recommended to disable Body fields so that the log data does not overgrow, especially in Production Environments.


The Log Settings fields are shown in the table below.

FieldDescription

Enable All Logs

Enables logging for all regions.

Disable All Logs

Disables logging for all regions.
HeaderEnables logging the Header values for the relevant region.
BodyEnables logging the content of the Body for the relevant region.
ParameterEnables logging the Parameter values for the relevant region.


In the Log Settings section, log settings are managed for the relevant API Proxy only. Logging can be disabled for Environment(s) under the Project Settings menu. In this case, no logs are kept even if the log settings for API Proxy are enabled.