Proxy forwarding mode

Proxy forwarding mode does not connect to a database. Instead, it turns a platform API into a reverse proxy: callers access the platform address, the platform forwards the request to a third-party HTTP/HTTPS API according to the configuration, and returns the response as-is or according to rules. It is suitable for unifying input and output parameters, hiding real addresses, attaching authentication and consolidating error codes.

Use cases

• A third-party system provides only fixed APIs, and you want the platform to handle authentication, rate limiting and logging uniformly.
• You need to attach a fixed Token / API Key when calling the third party, avoiding distributing the key to callers.
• Third-party error codes are inconsistent and need to be converted into platform business error codes.
• You need to bring third-party APIs into governance systems such as subscriptions, quotas, caching and monitoring.

Creation steps

1. Go to the Workbench and click Proxy Forwarding Mode.
2. Configure routing: platform request path, third-party domain and path, protocol and method.
3. Configure the request body type and response type as needed.
4. Configure third-party authentication (for example, Bearer Token).
5. Declare the externally exposed parameters in Request Parameters and Response Parameters on the right, and define upstream and downstream parameter mappings.
6. Use Test to verify the forwarding result, then save and release.

Route configuration

Field	Description	Example
API name	Display name within the platform	Query orders
Request path	External platform path with the unified project prefix	/order/query
Third-party domain/IP	Target host; may include http:// or https://	api.partner.com
Third-party path	Target API path	/v1/orders/query
Protocol	https or http; if the domain already includes a protocol, the protocol in the domain takes precedence	https
HTTP method	GET / POST / PUT / DELETE / PATCH	POST
Connection timeout	Timeout for establishing a connection with the third party, in ms	5000
Response timeout	Timeout for waiting for the third-party response, in ms	10000

The final address accessed by the platform is "protocol + third-party domain/IP + third-party path", and path joining automatically handles leading and trailing /. Neither the request path nor the third-party path may contain the * wildcard.

Request and response formats

Configuration	Options	Description
Request body type	JSON / x-www-form-urlencoded	Shown only for non-GET requests
Response type	JSON / text	Only JSON participates in error code mapping and structured responses

• When the request body type is JSON, Body parameters are assembled into a JSON object.
• When it is x-www-form-urlencoded, Body parameters are assembled into a form.
• Only the three safe request headers Accept, Accept-Language and Content-Type are passed through; other client request headers are dropped by default.
• Responses filter out hop-by-hop headers such as Content-Length, Connection and Transfer-Encoding.
• The maximum size read for a non-streaming response body is 10 MB; larger responses raise an error.

Third-party authentication

In Authentication Configuration, select the authentication method the platform uses to access the third party:

Type	Configuration	Actual effect
None	—	No authentication information is attached
Bearer Token	Token	Adds Authorization: Bearer <token>
Basic Auth	Username, password	Adds Authorization: Basic <base64>
API Key (Header)	Key name, key value	Attaches the key in the specified request header
API Key (Query)	Key name, key value	Attaches the key in the query parameters

Key storage

Third-party tokens, passwords and keys are stored in the API definition and are not visible to callers. Restrict API edit permissions to prevent keys from leaking through exports or screenshots.

Parameter mapping

Proxy mode request parameters support "platform parameter name → downstream parameter name" mapping:

• Parameters with the Query location are appended to the third-party URL query string.
• Parameters with the Header location are written into the forwarded request headers.
• Parameters with the Path location replace the {name} placeholders in the third-party path; the framework tries both columnName and paramName.
• Parameters with the Body location are assembled according to the request body type.

When no Query parameters are configured, the platform passes through all original query parameters from the caller; once Query parameters are configured, only the configured items and unconsumed original parameters are forwarded.

The response parameter side provides Import: paste a third-party JSON response example, and the platform parses it into tree fields automatically, making it easy to build the response structure quickly. Source parameter name maps third-party fields to externally exposed platform fields.

Path parameter security restrictions

Path parameter values cannot contain /, \, .., % or control characters, preventing traversal to unexpected endpoints within the allowed third-party host.

Error code mapping

Third-party errors preserve their original HTTP semantics by default. To convert them uniformly into platform business errors, configure Error Mapping:

Field	Description
Source type	HTTP status code or business code (reads the code field of the response JSON)
Source value	Status code or business code to match
Target error code	Converted platform error code; defaults to 40016 when left blank
Target message	Converted message text; when left blank, the platform tries to extract the third-party msg/message/error

Matching order: business codes are matched first; when the HTTP status code is 4xx/5xx, the status code is then matched. This takes effect only when the response type is JSON; text responses keep the third party's original semantics. When no mapping is configured, third-party HTTP errors are returned with their original status.

Egress security

The platform has a built-in proxy egress gate (SSRF protection):

• Only the http and https protocols are allowed.
• Hosts such as localhost and cloud provider metadata addresses (for example, 169.254.169.254 and 100.100.100.200) are hard-blocked.
• Access to intranet addresses is prohibited by default; once the allowlist is enabled, only allowlisted hosts (optionally with ports) can be accessed.
• Domain resolution failures are treated as denial (fail-closed).
• Related configuration: apigo.egress.enabled (default true), apigo.egress.allowed-hosts (comma, semicolon or space separated).

Blocked requests return 40022 "Target address is not allowed". In production, if access to intranet third-party systems is required, administrators should explicitly configure the allowlist instead of disabling the gate.

Testing and release

• Click Test at the bottom to open the debugging panel; fill in values by parameter location and send a real forwarding request.
• Test cases can save request snapshots for later regression.
• Mock rules can simulate responses when the third party is unavailable.
• After release, the API enters the current environment and can be used for credential authorization and subscriptions.

FAQ

Symptom	Cause	Resolution
40022 Target address is not allowed	The egress gate blocked the request or the host is not allowlisted	Check the target address and contact the administrator to configure the allowlist
40016 Third-party API call failed	Connection failure, timeout or third-party exception	Check the domain, port, timeout and third-party status
Third party returns 401/403	Authentication configuration is missing or incorrect	Check the Bearer / Basic / API Key configuration
Request body is empty	GET requests do not send a body, or no Body parameters are configured	Switch to POST or add Body parameters
Response fields are missing	No response parameters are declared	Import or add mappings in response parameters
Path parameter reports an illegal character	The Path value contains /, .., % or similar	Encode the path parameter or switch to Query

Related reading

• API definition
• Data plugins
• API testing
• Security governance