Skip to main content

Proxies

A Proxy defines a single API endpoint within a Collection. It specifies the path, HTTP methods, parameters, schemas, and optional workflow for that endpoint.

Proxy guides​

What is a Proxy?​

A proxy is the unit of routing in Zerq. When a request arrives at the gateway, Zerq matches it to a collection (by base path) and then to a proxy (by path and method).

Example mapping:

  • Incoming request: GET /payments/transactions?limit=10
  • Matched collection base path: /payments
  • Matched proxy path + method: /transactions + GET
  • Forwarded target path: /v2/txns (backend receives GET /v2/txns?limit=10)

Creating a Proxy​

From inside a collection, click Add Proxy. The creation form has multiple steps:

1. Basic Information​

FieldDescription
NameDisplay name (e.g., "List Transactions")
DescriptionShown in Developer Portal
HTTP MethodsOne or more of GET, POST, PUT, DELETE, PATCH

2. Path Configuration​

FieldDescription
PathIncoming path relative to collection base path (e.g., /transactions)
Target PathPath sent to the backend (can differ from incoming path)

Path parameters use {param} syntax:

Path:        /users/{userId}/orders/{orderId}
Target Path: /api/users/{userId}/orders/{orderId}

Wildcard paths use suffix /*:

Path:        /files/*
Target Path: /storage/*

Use wildcard routes only when suffix depth is variable and cannot be represented with stable {param} segments.

3. Headers​

Add headers that Zerq appends to the forwarded request for this specific proxy. Like collection-level headers, values can be static strings or environment variable references.

4. Parameters​

Define the parameters your endpoint accepts:

Path Parameters

Name:     userId
Type:     string
Required: true
Description: The unique user identifier

Query Parameters

Name:     limit
Type:     integer
Required: false
Default:  20
Description: Maximum number of results to return

Defining parameters enables:

  • Input validation
  • Developer Portal interactive testing with pre-filled fields
  • OpenAPI spec generation

5. Schemas​

Define JSON schemas for request and response bodies. Zerq uses these for:

  • Validation (request body)
  • Developer Portal documentation with examples
  • OpenAPI spec export

Example request schema:

{
  "type": "object",
  "required": ["amount", "currency"],
  "properties": {
    "amount": { "type": "number", "description": "Amount in cents" },
    "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] }
  }
}

6. Review​

Review the full configuration before saving.

Streaming responses​

Enable Streaming for endpoints that return Server-Sent Events (SSE) or long-lived streaming responses. When enabled, Zerq disables buffering, caching, and compression for this proxy.

Workflows​

Each proxy can have an optional Workflow — a node-based processing pipeline that runs for every request. Enable it from the proxy settings and click Edit Workflow to open the workflow builder.

→ See Workflows

Proxy status​

Proxies follow a draft → published lifecycle:

  • Draft: Only visible to admins; not accessible through the gateway
  • Published: Live — accessible to clients and visible in the Developer Portal

Toggle status from the proxy list or detail view.

Bulk operations​

Select multiple proxies using the checkboxes in the proxy list to apply an action to all of them at once:

ActionEffect
PublishSets all selected proxies to published status
UnpublishSets all selected proxies to draft status
DeletePermanently removes all selected proxies
caution

Bulk delete and unpublish immediately affect live traffic for all selected proxies.

Editing and Deleting​

  • Click the edit icon to modify any proxy setting
  • Click the delete icon to permanently remove a proxy
caution

Deleting a published proxy immediately makes that endpoint unavailable to all clients.

Duplicating a Proxy​

Duplicate a proxy to create a copy with similar configuration. The copy is created in draft status. You can duplicate within the same collection or into a different one.

Proxy URL structure​

A client calls a proxy at:

https://<gateway-host>/<collection-base-path>/<proxy-path>

Example:

https://api.example.com/payments/transactions

Where:

  • api.example.com = gateway host
  • /payments = collection base path
  • /transactions = proxy path