# REST outgoing connections

Reach any external REST API from every service - pools, timeouts and security included.

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](https://zato.io/docs/dev/rest/calling-apis.html), 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](https://zato.io/docs/dev/examples/graphql.html).

## Create a connection {#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**

[Video: New outgoing REST connection](https://zatosource-production.b-cdn.net/docs/gfx/rest/outconn-create.webm?v=1791298889)

Dashboard menu: Connections > Outgoing > REST

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](https://zato.io/docs/security/basic-auth.html), [API key](https://zato.io/docs/security/api-keys.html) or [Bearer token](https://zato.io/docs/security/bearer-tokens/index.html) definition - Zato attaches the credentials to every request, see [authentication](https://zato.io/docs/dev/rest/authentication.html)
- **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 {#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](https://zato.io/docs/dev/rest/calling-apis.html#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 {#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 {#timeouts}

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

```python
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 {#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](https://zato.io/docs/dev/delivery.html).

## Audit log {#audit-log}

Each outgoing connection records the requests it sends and the responses it receives in its own [audit log](https://zato.io/docs/admin/audit-log/index.html). This applies to user-defined connections only - internal ones are skipped entirely, and pings are never recorded.

## See also {#see-also}

- [Calling REST APIs](https://zato.io/docs/dev/rest/calling-apis.html) - Invoking connections from Python - GET, POST, parameters and headers
- [Authentication](https://zato.io/docs/dev/rest/authentication.html) - The security definitions a connection authenticates with
- [REST adapter](https://zato.io/docs/dev/rest/rest-adapter.html) - Declarative API calls with response mapping and no boilerplate
- [Delivery retries and dead-letter queues](https://zato.io/docs/dev/delivery.html) - Retries, queues and dead-letter queues for requests that could not be delivered
- [Error handling](https://zato.io/docs/dev/rest/error-handling.html) - What your service receives when an endpoint fails

## Learn more {#learn-more}

- [REST integration overview](https://zato.io/integrations/rest/) - Start here to see how teams build REST integrations
- [In-depth API tutorial](https://zato.io/tutorials/main/01.html) - Master architectural patterns for production-ready integrations
- [Modern REST API tutorial](https://zato.io/tutorials/rest-api/python.html) - Design, build and secure REST APIs with Python