Docs
Start typing to search…

API Proxy

API proxy lets you make direct API requests through a Connection.
API Proxy sends your request to the external application without changes and returns the exact response the external app provided.

Proxy API does two things with your requests:

  • Adds Base URL to the path you provided (unless you provide full URL)
  • The only thing API proxy does is add authentication headers and handle credential refreshes.

Using API Proxy

REST API

To make a Proxy request using REST API, simply prefix the request with

https://api.integration.app/connections/<connectionSelector>/proxy

Connection selector can be one of the following:

  • Integration key (if there is only one connection for the integration)
  • Integration ID (if there is only one connection for the integration)
  • Connection ID

Let's say you created a connection to the Hubspot CRM and want to make a request to the following hubspot endpoint:

https://api.hubapi.com/crm/v3/owners/

you would instead make a request to

https://api.integration.app/connections/<connectionId>/proxy/crm/v3/owners/

Or if you don't want to rely on the base URL, you can provide the full URL:

https://api.integration.app/connections/<connectionId>/proxy/https://api.hubapi.com/crm/v3/owners/

The HTTP method and body you use for this request will be proxied to the underlying application's API.

JavaScript SDK

To make a Proxy request using JavaScript SDK, use proxy property of the Connection:

const response = integrationApp.connection('connection-id').proxy.get('/crm/v3/owners/')

You can call .get, .post, .patch, .put and .delete requests of the proxy property.
First parameter is an API path and the second is an optional object with the request payload for post, patch, and put methods.

Edge Cases

Headers

There are special headers that are used by the proxy infrastructure. They will be ignored by the proxy and not passed to the underlying application.

Here is the full list of these headers:

  • host
  • x-request-id
  • x-real-ip
  • x-forwarded-for
  • x-forwarded-host
  • x-forwarded-port
  • x-forwarded-proto
  • x-forwarded-scheme
  • x-scheme
  • x-original-forwarded-for
  • x-different-name
  • x-request-start
  • x-using-nginx-controller
  • x-amzn-trace-id
  • forwarded-for-header
  • proxy-protocol
  • real_ip_header
  • real_ip_recursive
  • cdn-loop
  • cf-ipcountry
  • cf-ray
  • cf-visitor
  • cf-connecting-ip
  • connection
  • authorization
  • content-length

Error Handling

Proxy will return the same status code, headers, and body that the underlying application's API returns. The only exception is handling credential refreshes.

If proxy receives a response indicating that the credentials have expired, it will attempt to refresh the credentials once.

Here are the possible outcomes when this happens:

  • If refresh is successful – it will retry the request and return the second response (successful or not).
  • If refresh process fails – it will return the original response.

Limits

Proxy API has the same limits as the rest of our API endpoints. See Limits.

Updated 16 days ago