REST outgoing connections

An outgoing REST connection holds everything needed to reach one external API - the address, the URL path, the credentials, the connection pool and the timeout. You create a connection once in the Dashboard and every service invokes it by name, with no URLs or credentials in Python code.

For external systems that expose a GraphQL API rather than REST, Zato offers dedicated GraphQL outgoing connections.

Create a connection

To create a connection, go to Connections > Outgoing > REST in the Dashboard, click Create a new REST outgoing connection and fill in the form:

1. Name: Customer API
2. Host: the base address of the API, e.g. https://api.example.com
3. URL path: the endpoint path, which can include {placeholders} for parameters
4. Data format: JSON
5. Click OK

After you click OK, services invoke the connection by its name - no server needs to be restarted.

The same form also takes:

• Security: a Basic Auth, API key or Bearer token definition - Zato attaches the credentials to every request, see authentication
• Pool size: how many network connections Zato keeps open to the endpoint - requests above that number wait for a connection to free up rather than opening new ones
• Timeout: how many seconds an invocation waits for the endpoint to answer

One connection is one endpoint

A connection points to one endpoint. You can put {placeholders} in its URL path for the parts that vary from call to call, and each call gives their values in params, together with the query string, as path and query parameters explains - /customers/{customer_id} reaches any customer.

For an external system with several endpoints on one host - customers, orders, invoices - you create one connection per endpoint, each with its own name.

Import connections from OpenAPI

When the external system publishes an OpenAPI specification, you can create its connections in bulk instead of one by one:

1. On the same page, click Import OpenAPI
2. Paste the OpenAPI YAML or JSON into the editor, or enter a URL to fetch it from
3. In the next step, select which endpoints to import from the table
4. Click OK

The import creates one outgoing REST connection for each selected path, with the host and URL path pre-configured. If the specification defines authentication - Basic Auth, Bearer token or API key - the matching security definitions are created too.

An OpenAPI specification describes authentication requirements but never includes actual credentials, so after the import you enter them yourself:

• Basic Auth: go to Security > HTTP Basic Auth, find the definition and click Change password
• API key: go to Security > API Keys, find the definition and click Change secret
• Bearer token: go to Security > OAuth > Outgoing > Client Credentials and enter the client ID, the client secret and the token endpoint URL

Once the credentials are in place, the connections that use these definitions authenticate automatically.

Timeouts

A connection waits for the endpoint as long as its Timeout field says. A single call can override it:

request = {'Hello': 'World'}
response = conn.post(request, timeout=30)

When neither the connection nor the call sets a timeout, the wait defaults to the Linux kernel's default of approximately 2 minutes.

A response can be of any size - there is no limit on how much an endpoint may send back. A large response only needs a timeout long enough for all of it to arrive.

Retries and guaranteed delivery

What happens to a request the endpoint could not take - a connection error, a timeout or a rate-limited response - is decided in the connection's Delivery tab, where you set how many times it is retried, whether it then waits in the connection's queue until it goes through, and what its dead-letter queue does with a request that never did. All of it is on one page, Delivery retries and dead-letter queues.

Audit log

Each outgoing connection records the requests it sends and the responses it receives in its own audit log. This applies to user-defined connections only - internal ones are skipped entirely, and pings are never recorded.

See also

Learn more