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
- Request Arrival: For each HTTP/HTTPS request arriving at API Gateway, if REST API Call policy is active, the call process is initiated.
- 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?
- 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)
- 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
- 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)
- 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.
- SSL/TLS Certificate Support: Connect to secure (HTTPS) backend services with custom certificates. Centralized certificate management with Certificate Manager integration.
- 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) | Certificate Enabled: true. Selected certificate: “Production_Client_Cert”. URL: https://secure-backend/api. Timeout: 60 seconds. | Request is sent with client certificate, backend service verifies certificate, 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-HeaderNew Headers: - Name, Description, Value/Variable, Prefix (if Variable is selected: BEARER, BASIC, etc.) - Example: Name: Authorization, Value: Bearer ${token.jwt}, Prefix: BEARERPARAMETER 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? SETTINGS Tab: Certificate Enabled: Toggle - Active: Certificate dropdown appears. - Selection: Select certificate from Certificate Manager. - You can add new certificate with [Add Certificate] button. |
| 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. |
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. |
Tips and Best Practices
Things to Do and Best Practices
| Category | Description / Recommendations |
|---|---|
| URL Management | Bad: Hard-coding URLs: https://api.prod.com/usersGood: Using environment variable: ${env.api.url}/usersBest: 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. |