Creating Passthrough APIs in Frends

Passthrough APIs allow you to forward requests from the Frends API endpoints to your system's provided APIs, in the case where data conversion or other logic is not needed. They are excellent to use to keep a coherence in your API branding, having all used endpoints within the same domain, without requiring much configuration or overhead from creating a Process in between where nothing really happens.

Requirements

In order to use Passthrough APIs, you need to have cross-platform Agent in use. Legacy Agents do not support the feature.

How to create a Passthrough API

After you have created an API specification, as guided in How to create an API with Frends, you can access the Passthrough API editor by clicking on Create Passthrough API button in your API's management view.

In the editor, you can choose to create a passthrough for any single endpoint in your API, or for all of the endpoints at once by proxying the API's base URL as a whole to another API.

Configure Passthrough API URL

First thing to set up for a passthrough API is the URL the passthrough should proxy to. This is the target URL for requests being forwarded from Frends.

The URL is built with three to four sections that are defined separately. The sections are separated by a forward slash (/), except for the query parameters, which are separated by a question mark (?).

• First part of the URL covers the server name or base URL the request is sent to.

• Second part is the base path or directory to the endpoint. This can be a single value or multiple values separated by forward slashes.

• Third part is the actual endpoint of the API the request is directed to.

• If query parameters are used, they form the fourth section of the target URL.

You can use plain text values as well as Handlebars with C# expressions and reference values to form each of the sections.

The following reference values are available to use with Handlebars:

• Any existing Environment Variables with #env

• Passthrough API specific #api reference values:

  • #api.BasePath: URL of the API specified in the API spec, not including the server name. For example /api/crm/v1

  • #api.OperationPath: Name of the endpoint used, such as /customers

  • #api.QueryParameters: Query parameter string that was provided for the request

Values can be combined, edited, disregarded and set as necessary for the target system to accept the request.

An example

The API reference values get their values from the original request that was made to Frends. As an example, if the request made to Frends was to URL https://frends-test.mycompany.com/api/crm/v1/customers?id=123456, the API reference values will become:

• #api.BasePath: api/crm/v1

• #api.OperationPath: customers

• #api.QueryParameters: id=123456

If we want to forward this request to another API performing the actual operation, where matching URL should be https://crm-company.com/api/client-access/v1/customer/123456, we should create the passthrough configuration as

• Server name: {{#env.crm_company.server}}

• API base path: api/client-access/v1/customer

• API operation: {{#api.QueryParameters.Split('=')[1]}}

• Query parameters: none, leave empty

CORS

In addition to the Target URL, you can configure the Cross-Origin Request Sharing rules, allowing specific domains to perform CORS requests to your API. By default this is disabled, disallowing all CORS requests.

If enabled, a comma (,) separated list of domains can be provided, in addition to an asterisk (*) to allow all domains.

Passthrough Headers

If specific headers and values are needed to be added to, overwritten or removed from the original headers provided in the requests, they can be specified here.

• Add: Appends the Header value to an existing Header name. If the Header doesn't exist, it adds it.

• Overwrite: Overwrites the Header name with the provided Header value.

• Remove: Removes the Header name if it exists.

Note that Handlebars, C# or reference values cannot be used.

Passthrough authentication

API Policies can be used to create authentication for the Passthrough APIs, requiring users of your API to use authentication before the request is passed through.

If your target system requires specific authentication, providing the authentication headers or query parameters in addition to the original request is possible with the features explained above.

It's also possible to enable public access for your passthrough API, and require the original request to include authentication headers or other details that are then passed through to the target service.

Passthrough conflicts

If an endpoint already has a linked Process attached to it, passthrough for that endpoint cannot be created. Similarly, if specific endpoints have either linked Process or passthrough created for them, those will take priority over the All endpoints passthrough setting. All endpoints passthrough will only apply to endpoints that have no specified passthrough or linked Process attached to them.

Passthrough limitations

Passthroughs are created to allow proxying API requests from Frends to another system that provides the actual API service, in order to allow serving your users and customers from an unified API.

While it allows some customization and dynamic address generation as shown in the example, it provides generally no further adjustments to the content. If more customization and logic are necessary for your use case, for example to move some URL content to headers and/or request body or vice versa, creating a Process to fulfill the requirements is the way to go.