API Call

You can securely and controllably call external REST APIs through API Gateway to enable data integration. You can manage request and response transformations and use error handling mechanisms

This document describes the detailed usage of a specific policy. If you are using Apinizer policy structure for the first time or want to learn the general working principles of policies, we recommend that you first read the What is Policy? page.

Overview

API Call policy establishes service-to-service communication in microservice architectures by calling other REST APIs through API Gateway. It routes incoming requests to backend systems, processes responses, and integrates them into the API Proxy flow. This enables fetching data from external services, enriching requests, or combining responses from multiple sources.

What is its Purpose?

• Route requests passing through API Gateway to another REST API to enable service-to-service communication in microservice architectures.
• Enrich incoming requests, transform them, and create combined responses by gathering data from multiple backend services (API Orchestration).
• Create a secure and manageable bridge to fetch or send data to external systems (CRM, ERP, payment gateways, etc.).
• Perform data transformation by manipulating headers, parameters, and body on request and response messages.
• Improve performance and reduce load on backend systems by caching results of frequently used API calls using cache mechanisms.

Working Principle

1. Request Arrival: For each HTTP/HTTPS request arriving at API Gateway, if REST API Call policy is active, the call process is initiated.
2. Policy Check: The system checks in the following order:
   • Is a condition defined? If so, is the condition met?
   • Is the policy active (active=true)?
   • Is a variable used or is Apinizer default used?
3. Request Preparation (Before Call): Before sending the request:
   • Body is cleared or new content is added
   • Headers and parameters are manipulated (add/remove)
   • Data Manipulation rules are applied
   • Cache check is performed (returns from cache if available)
4. API Call: Request is sent to the defined URL with HTTP method:
   • Synchronous: Response is awaited and processing continues
   • Asynchronous: Process completes without waiting for response
5. Response Processing (After Call - Only Synchronous): Incoming response is processed:
   • Transformation is performed on body (NOT_CHANGE, REPLACE, CLEAR)
   • Headers and parameters are manipulated
   • Data Manipulation rules are applied
   • Saved to cache (if active)
6. Error Handling: Customizable HTTP status code and error message are returned for connection errors, timeouts, or unexpected responses.

Features and Capabilities

Basic Features

• Call Type Selection: Support for Synchronous (wait for response) or Asynchronous (fire-and-forget) mode. Response processing is not performed in async mode.
• HTTP Method Support: Supports all HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE.
• Timeout Management: Prevents infinite waits and protects system resources by defining maximum wait time in seconds for API calls.
• Active/Passive Status Control: Easily change policy’s active or passive status (active/passive toggle). Policy is not applied in passive state but its configuration is preserved.
• Condition-Based Application: Determine when the policy will be applied by creating complex conditions with Query Builder (e.g., only for specific endpoints or header values).

Advanced Features

• Request/Response Manipulation: Comprehensive manipulation of body, headers, and parameters in Before Call and After Call stages. Supports XML, JSON, RAW, URL-Encoded formats.
• Data Manipulation: Data transformation with ADD (add), REPLACE (replace), DELETE (delete) operations between source and target variables. Dynamic data processing using Variable system.
• Secure HTTPS and mTLS: On the request Settings tab you can set timeout and secure connection options (TrustStore, KeyStore, optional PEM certificate, protocols, hostname verifier) for TLS/mTLS to the backend; certificate and KeyStore management aligns with Secret Manager.
• Cache Mechanism: Support for Distributed or Local cache. Variable-based cache key definition, capacity and TTL settings, option to cache null responses.
• Test Helper: Automatically generate URL for API call. Select endpoint from existing API Proxies or Proxy Groups, test based on environment.
• Export/Import Feature: Export policy configuration as ZIP file. Import to different environments (Development, Test, Production). Version control and backup capability.
• Policy Group and Proxy Group Support: Manage multiple policies within Policy Group. Bulk policy assignment to Proxy Groups. Centralized updates and deploy operations.
• Deploy and Versioning: Deploy policy changes to live environment. See which API Proxies use it (Policy Usage). Proxy Group and Policy Group usage reports.

Usage Scenarios

Scenario	Status	Solution (Policy Application)	Expected Behavior / Result
Microservice Integration	Order API needs to call payment service	POST call is made to payment service with REST API Call policy on requests arriving at order endpoint. Order information is sent in body.	Payment service response is received, if successful order is confirmed. Timeout 30 seconds.
Data Enrichment	User profile API comes only with ID but detailed information is needed	GET call is made to CRM system with userId from incoming request body. CRM response is added to existing response with Data Manipulation.	Returns to client with user ID + full profile information (name, surname, email) combined.
Authentication Token Management	Backend service expects JWT token instead of API Key	X-API-Key is taken from Request Headers, sent to Authentication API. Returned JWT token is added to Authorization header in Before Call stage.	Backend service is called with valid JWT token. Client continues to use API Key.
Performance with Cache	Product catalog API goes to database on every call	Catalog service is called with REST API Call. Cache active, capacity: 1000, TTL: 300 seconds. Cache By: “product.category” variable. Storage: Distributed.	First call goes to backend, result is cached for 5 minutes. Calls for same category return from cache.
Async Log Sending	Every API call needs to be logged to external log system	POST is made to log service with Asynchronous REST API Call. Request details are sent in body. Timeout: 5 seconds.	Log service response is not awaited, main request flow continues uninterrupted. Fire-and-forget logic.
Third-Party API Gateway	Payment gateway expects special header format	All headers are deleted in Before Call stage (removeAllHeadersBeforeCall: true). New headers are added: X-Merchant-ID, X-Transaction-Type, Authorization (Bearer token). Body is converted from XML to JSON.	Payment gateway receives request in expected format, integration succeeds.
Secure Communication with Certificate	Backend service requires mutual TLS (mTLS)	Enable secure connection on the request Settings tab and use Configure to select KeyStore and TrustStore. URL: https://secure-backend/api. Timeout: 60 seconds.	Request is sent with client certificate, backend verifies mutual TLS, secure communication is established.

Configuring Policy Parameters

In this step, users can create a new policy or configure existing policy parameters to define access rules. Defined parameters directly affect how the policy works (e.g., which IPs will be allowed, geographical restrictions, conditional activations, etc.). This allows the policy to be customized according to organization-specific requirements and managed centrally.

Creating New API Call Policy

Configuration Steps

Step	Description / Operation
Step 1: Go to Creation Page	- Go to Development → Global Settings → Global Policies → API Call from left menu. - Click [+ Create] button at top right.
Step 2: Enter Basic Information	Policy Status (Policy Status): Shows Active/Passive status. New policies are active by default. Name (Name) Required: Example: Payment_Gateway_Call - Enter unique name, does not start with space. - System automatically checks. Green checkmark: available. Red X: existing name. Description (Description): Example: “Makes API call to payment gateway for order confirmation” - Max. 1000 characters. - Explain policy’s purpose.
Step 3: Configure Call Type and Basic Settings	Call Type (Call Type): - SYNCHRONOUS: Response is awaited, processing continues. Response processing is performed. - ASYNCHRONOUS: Fire-and-forget. Response is not awaited, response processing is not performed. HTTP Method Required: Select from dropdown (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE) Base URL Required: Example: https://api.payment-gateway.com/v2/charge - You can select URL from existing API Proxies with Test Helper (⚙️ icon). Timeout Required: In seconds. Example: 30 (30 seconds). Min: 1. - If API does not respond, timeout error is returned after this duration.
Step 4: Request (Before Call) Configuration	BODY Tab: Clear Body Before Call: Toggle to activate/deactivate - Active: Incoming request body is cleared. - Passive: Incoming body is used as is. Use Message Template (if Clear Body is active): - Content Type: XML, JSON, RAW, URL_ENCODED - Body Content: Enter template in textarea. You can use variables: ${variable.name} - If URL Encoded is selected: Key-Value table appears. Request Data Manipulation: - Click [+ Add] button. - Operation: ADD, REPLACE, DELETE - Source: Value or Variable - Target: Value or Variable (targetName required in ADD) HEADER Tab: Remove All Headers Before Call: Toggle - Active: All headers are deleted. - Passive: Headers are preserved. Deleted Headers (if Remove All is passive): - Add header names to delete in list format: X-Old-Header New Headers: - Name, Description, Value/Variable, Prefix (if Variable is selected: BEARER, BASIC, etc.) - Example: Name: Authorization, Value: Bearer ${token.jwt}, Prefix: BEARER PARAMETER Tab: - Same logic as Header. Used for query parameters. CACHE Tab: Enable Cache: Toggle Apply By (Cache By): Select variable (e.g., user.id, product.category) Capacity Required: Example: 1000 (1000 records) TTL Required: In seconds. Example: 300 (5 minutes) Cache Storage Type: DISTRIBUTED (distributed) or LOCAL (local) Cache Null Responses: Checkbox - Should null responses also be cached? Dynamic TTL: Enable with toggle. When enabled, cache TTL is dynamically calculated from the API call response. See Dynamic TTL section for details. SETTINGS Tab: Timeout: Required, in seconds. You manage request duration on this tab; keep it consistent with the call timeout in the upper section. Secure connection (mTLS) settings: Turn on enable secure connection under the section title. When on, the summary shows KeyStore status, TrustStore and PEM server certificate if set, selected TLS protocols, and hostname verifier type. Click Configure (gear) for full editing; the button is disabled when secure connection is off. In the Configure dialog: Skip SSL verification disables server certificate validation and hides TrustStore, KeyStore, and certificate panels—use only in trusted test environments. When verification is on, select TrustStore and KeyStore from the pool or create a new KeyStore with +; choose a PEM Certificate from the pool or create a new one. Under Protocol settings, choose supported TLS protocol versions and the hostname verifier. This policy flow uses pool selection and new entries rather than direct file upload; a warning is shown at the bottom of the dialog. Click Save to apply and close.
Step 5: Response (After Call) Configuration (Only SYNCHRONOUS)	BODY Tab: After Call Body Operation Type: - NOT_CHANGE_BODY: Incoming response is returned as is. - REPLACE_BODY: Incoming response is completely replaced. - CLEAR_BODY: Incoming response is cleared, new body is created. Use Message Template (if CLEAR_BODY is selected): - Content Type: XML, JSON - Body Content: Enter response template in textarea. Original Message Data Manipulation: - Same logic as Before Call. ADD, REPLACE, DELETE on incoming response. HEADER and PARAMETER Tabs: - Same structure as Request. Header/parameter manipulation for After Call.
Step 6: Define Condition (Optional)	- Go to Condition tab. - Conditions determine when the policy will be active. Examples: - Environment-based: Header = X-Environment, Operator = Equals, Value = production - API Key-based: Header = X-API-Key, Starts With = PROD- - Endpoint-based: Path = /api/payment/*
Step 7: Customize Error Message (Optional)	- Go to Error Message Customization tab. - Customize message to return when API call fails. Default: { "statusCode": 500, "message": "REST API call failed" } Custom: { "statusCode": 502, "errorCode": "PAYMENT_GATEWAY_ERROR", "message": "Payment service is not responding", "timestamp": "${current.time}" }
Step 8: Save	- Click [Save] button at top right. Checklist: Unique name. Required fields filled. At least one IP or group exists Result: - Policy is added to list. - Can be bound to APIs. - If global policy, automatically applied.

For descriptions of Conditions and Error Message Customization panels, you can review the Conditions and Error Message Customization (Error Message Customization) sections on the What is Policy? page.

For a complete guide on all layers, priority order and scenario examples of the error message configuration system, see the Error Message Configuration Guide page.

Deleting Policy

For deletion steps of this policy and operations to be applied when in use, you can refer to the Deleting Policy section on the What is Policy? page.

Exporting/Importing Policy

For export (Export) steps of this policy and available options, you can refer to the Exporting/Importing Policy section on the What is Policy? page.

Binding Policy to API

For the process of how this policy will be bound to APIs, you can refer to the Binding Policy to API section on the Policy Management page.

Advanced Features

Feature	Description and Steps
Variable-Based Dynamic URL	You can create dynamic endpoints using variables in URL. - Define variable: backend.base.url = https://api.backend.com - In URL field: ${backend.base.url}/users/${user.id}/profile - Values are automatically filled at runtime.
Chained API Calls (Chain Calls)	You can create data flow by running multiple REST API Call policies sequentially. - Call Authentication API with first policy, get token. - Save token to variable: auth.token - Add ${auth.token} to Authorization header in second policy. - Call Data API with second policy.
Conditional Caching	Cache is active only in certain conditions. - Activate cache. - In Condition section: Header = X-Cache-Control, Equals = enable - Client activates cache by sending header when cache is needed.

Dynamic TTL

Dynamic TTL automatically calculates the cache time-to-live (TTL) from a value in the API response instead of using a fixed value. For example, if your backend service returns an expireAt field in the response, the cache remains valid until that date.

Configuration Fields

Field	Description
Enable Dynamic TTL	Toggle on/off. When enabled, the static TTL field is hidden and dynamic TTL settings appear.
TTL Source Variable	The variable from which the TTL value will be read. Can be a response header, response body (JSONPath/XPath), or another context variable. Example: $.expireAt from the response body.
Value Format	Specifies the format of the value read from the selected variable. The following formats are supported:

Supported Value Formats:

Format	Description	Example Value
ISO 8601 DateTime	Standard ISO 8601 date format. Accepts UTC, offset, or timezone-less values.	2026-03-26T15:30:00Z, 2026-03-26T15:30:00+03:00, 2026-03-26T15:30:00, 2026-03-26
Custom DateTime Format	Custom format using Java DateTimeFormatter pattern. An additional pattern field appears when selected.	Pattern: dd.MM.yyyy HH:mm:ss → Value: 26.03.2026 15:30:00
Unix Epoch (seconds)	Unix epoch timestamp in seconds.	1743004200
Unix Epoch (milliseconds)	Unix epoch timestamp in milliseconds.	1743004200000
Expires In (seconds)	Relative duration indicating how many seconds the response is valid.	300 (5 minutes)
Expires In (milliseconds)	Relative duration indicating how many milliseconds the response is valid.	300000 (5 minutes)
Duration String	Human-readable duration string.	1h, 30m, 3600s

Additional Settings

Field	Description
Value is inside a JWT Token	Checkbox. When selected, the source variable value is first decoded as a JWT token, then the TTL value is read from the specified claim.
JWT Claim Name	The claim name to read after JWT decoding. Supports simple claim names (e.g., exp) or JSONPath (e.g., $.data.expireAt).
Offset (seconds)	Safety margin in seconds subtracted from the calculated TTL. For example, with a 30-second offset, the cache expires 30 seconds before the actual expire time. Used to compensate for clock drift or network latency.
Fallback TTL (seconds)	Fallback TTL value (in seconds) used when dynamic TTL cannot be calculated (parse error, variable not found, etc.). If not defined, the policy’s static TTL value is used.

Example Scenario

Your backend service returns the following response:

{
  "data": { "price": 99.90, "currency": "USD" },
  "expireAt": "2026-03-26T15:30:00Z"
}

Configuration:

1. Enable Dynamic TTL: On
2. TTL Source Variable: Response body → JSONPath: $.expireAt
3. Value Format: ISO 8601 DateTime
4. Offset: 30 (30-second safety margin)
5. Fallback TTL: 300 (5 minutes if parse fails)

The cache will remain valid until the date in the expireAt field (minus 30-second offset).

Tips and Best Practices

Things to Do and Best Practices

Category	Description / Recommendations
URL Management	Bad: Hard-coding URLs: https://api.prod.com/users Good: Using environment variable: ${env.api.url}/users Best: Environment-based management with Variable + Config: ${backend.url} = https://test-api.com in test environment, https://prod-api.com in production
Timeout Values	Bad: Very high timeout (120 seconds) - System resources are exhausted Good: Average timeout (30 seconds) - Sufficient in most cases Best: Optimized timeout according to backend service response time. Database queries: 10 seconds, External API: 30 seconds, Payment: 60 seconds
Cache Strategy	Bad: Same cache setting for all APIs - Unnecessary cache Good: Endpoint-based cache - Product list: 5 minutes Best: Variable-based cache + Null response control. Cache By: user.tier → Premium user: 1 minute, Free user: 10 minutes. Cache Null Responses: false (empty responses should not be cached)
Error Handling	Bad: Default error messages - User doesn’t understand Good: Custom error messages - “Backend service is not responding” Best: HTTP status code + custom error code + contextual message: { statusCode: 504, errorCode: "PAYMENT_TIMEOUT", message: "Payment service did not respond within 30 seconds", retryAfter: 60 }
Header Manipulation	Bad: Deleting all headers and manually adding - Security risk Good: Adding/deleting only necessary headers Best: Remove All Headers: false. Delete only sensitive headers (Authorization, Cookie). Add headers backend needs. Add correlation-id for trace.

Security Best Practices

Security Area	Description / Warnings
Certificate Usage	Warning: Connecting to HTTPS backends without certificate creates security vulnerability. Recommendation: Always add certificate to systems requiring mutual TLS (mTLS). Check certificate revocation. Expired certificates give warning. Critical: Do not use self-signed certificate in production environment.
Sensitive Data Transmission	Warning: Do not send information like API Key, token, password in body as plain text. Recommendation: Define sensitive data as Variable, store encrypted. Send in header: Authorization: Bearer ${secure.token} Critical: Be careful not to log sensitive data. Mask password fields in Data Manipulation.
Asynchronous Call Security	Warning: In async calls, response cannot be checked, errors may be missed. Recommendation: Use Synchronous for critical operations. Use async only for side operations like log, notification. Critical: Operations like payment, order confirmation should not complete without receiving actual response.
Input Validation	Warning: Do not send requests to backend without validating incoming requests. Recommendation: Add input validation in Before Call stage. Filter risky characters for XSS, SQL Injection. Perform sanitization with Data Manipulation. Critical: Ensure data is not sent in format other than what backend expects.
Rate Limiting	Warning: REST API Call policy does not do rate limiting, backend may be overloaded. Recommendation: Use Rate Limiting policy together with REST API Call. Do not overload backend system. Critical: Rate limiting at API Gateway level is required for DDoS protection.

Things to Avoid

Category	Description / Warnings
Infinite Timeout	Why to avoid: If timeout value is very high (e.g., 300 seconds), non-responding backends consume system resources. Connection pool may fill up. Alternative: Use reasonable timeout values (between 5-60 seconds). Optimize backend service. Use async call if necessary.
Intensive Calls Without Cache	Why to avoid: Calling same data repeatedly tires backend, increases response time, increases cost. Alternative: Activate cache for data that doesn’t change frequently (product catalog, settings). Set TTL according to data update frequency.
Unnecessary Data Manipulation	Why to avoid: Performing complex data manipulation on every request/response reduces performance. CPU usage increases. Alternative: Prefer changing backend service to send data in desired format. Use data manipulation only when necessary.
Frequent Changes in Global Policy	Why to avoid: If global policy is used in multiple APIs, one change affects all APIs. Error risk increases in production. Alternative: Test global policy in test environment. Use local policy for critical APIs. Take backup before changes.

Performance Tips

Criterion	Recommendation / Impact
Connection Reuse	Recommendation: Apinizer manages backend connections with connection pool. If multiple calls are made to same backend, connection is reused. Impact: New TCP connection is not opened for each call, latency decreases. SSL handshake overhead decreases.
Cache Hit Ratio	Recommendation: Do not keep cache capacity too low. Give high capacity to heavily used endpoints. Make correct key selection with Cache By. Impact: If cache hit ratio is 80%+, backend load decreases by 80%. Response time speeds up 10-100x.
Async vs Sync Selection	Recommendation: Use async for non-critical, slow, operations that don’t require response (log, notification, analytics). Impact: Main request flow is not blocked. End-user response time decreases. Backend timeout risk decreases.
Data Manipulation Optimization	Recommendation: Do not perform unnecessary parsing on large JSON/XML files. Manipulate only necessary fields. Access field directly with XPath/JSONPath using variables. Impact: CPU usage decreases by 50-70%. Memory consumption decreases. Throughput increases.
Timeout Tuning	Recommendation: Measure backend service average response time. Set timeout as average + 2x standard deviation. Example: Avg: 2s, StdDev: 1s → Timeout: 4s Impact: Unnecessary timeouts don’t occur. Non-responding backends fail quickly. Resource leak is prevented.

Frequently Asked Questions (FAQ)

Category	Question	Answer
General	What is the difference between REST API Call policy and API Proxy?	API Proxy: Public endpoint exposed to clients. REST API Call: Makes call to another backend API as policy. REST API Call policy can be used within an API Proxy. Example: Client → API Proxy (/payment) → REST API Call → Backend (/charge)
General	Can I use multiple REST API Call policies in the same API Proxy?	Yes. You can use multiple REST API Call policies with different conditions or sequentially. Example: First policy authentication, second policy data fetch.
Technical	What is the practical difference between Synchronous and Asynchronous?	Synchronous: Request is sent, response is awaited, response is processed, returned to client. Total time increases but control is complete. Asynchronous: Request is sent, response is not awaited, immediately returned to client. Total time decreases but backend success/error information cannot be obtained.
Technical	Is there risk of data corruption or stale data in cache?	Risk is minimal if TTL is set correctly. Cache is cleared when TTL expires. Use Cache Policy for manual cache clear. Keep TTL low for critical data (30-60 seconds).
Usage	What is Test Helper, how is it used?	Test Helper makes it easier to create URL for REST API Call. Lists existing API Proxies, automatically fills URL of selected proxy. You can make environment selection. Opens by clicking ⚙️ icon.
Usage	What is the difference between ADD and REPLACE in Data Manipulation?	ADD: Adds a new field. Example: Add new field to response JSON: response.user.fullName = ${user.firstName} + ${user.lastName} REPLACE: Changes existing field. Example: Replace value of request.body.price with ${discounted.price}.
Error	I’m getting “PolicyRestApiCallConnectionException” error. Solution?	Backend service is not accessible. Check: Is URL correct? Is backend up? Is there network firewall? Is certificate needed? Is timeout too low (increase it)?
Error	Cache is not working, goes to backend on every call. Why?	Check: Is cache enabled? Are capacity and TTL defined? Is Cache By variable set correctly? Are requests coming with same cache key? If cache storage type is distributed, is cache server up?
Performance	What is the performance overhead of REST API Call policy?	Minimal. Additional latency: 5-20ms if data manipulation exists, less than 2ms if not. If cache is active, there is no backend call on cache hit, latency decreases by 90%. Overhead is almost zero in asynchronous mode.