API Gateways

When you publish an API Endpoint in Tinybird, it is available via api.tinybird.co, api.us-east.tinybird.co or the API Gateway URL that corresponds to your Workspace region (see API Endpoint URLs) for more info and a full region list. These API Endpoints are secured via Auth Tokens that are managed inside your Tinybird Workspace.

Many users embed these Tinybird URLs directly into their applications using appropriately scoped Auth Tokens.

However, there are some cases where it is desirable to put the Tinybird API Endpoints behind an API Gateway, such as:

  • Branding/white labeling: to present a unified brand experience to your users

  • Security: to avoid exposing Auth Tokens & underlying technology

  • Compliance: some industries have strict regulations around data privacy and security

  • Flexibility: to add Tinybird to an existing API architecture

Alternative approaches

An API Gateway is not always necessary and can add additional complexity (and cost). Carefully consider whether it is the right approach for you.

Some requirements can be met in different ways:

  • Appropriately scope the Auth Token that is used inside your application. Exposing a read-only token has limited security concerns as it cannot be used to modify data, and can be invalidated by you at any time.

  • Use Row-Level Security to ensure that an Auth Token only provides access to the appropriate data.

Amazon API Gateway

Amazon API Gateway is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale. Using Amazon API Gateway, you can create an API Gateway to any Tinybird API without writing code, using the AWS console.

You can read more about using Amazon API Gateway here.

The steps to create a basic Reverse Proxy using Amazon API Gateway are as follows:

  • Access the API Gateway console

  • Select Create API, then HTTP API

  • Click Add Integration and select HTTP

  • Configure the integration with the method GET and the full URL to your Tinybird API with its token, e.g. https://api.tinybird.co/v0/pipes/top-10-products.json?token=p.eyJ1Ijog...

  • Set a name for the API and click Next

  • On the Routes page, set the method to GET and configure the desired Resource path e.g. /top-10-products

  • Click through the rest of the step to create the API

You can find more information about applying a custom domain name to Amazon API Gateway here.

Google Cloud Apigee

Apigee is Google Cloud’s native API management tool to build, manage, and secure APIs. Using Apigee, you can create a Reverse Proxy to any Tinybird API without writing code, using the Google Cloud console.

You can watch Google’s own Apigee tutorial for a more in-depth guide on how to use the service.

The steps to create a basic Reverse Proxy using Apigee are as follows:

  • Access the Apigee console

  • Add a new Reverse Proxy

  • Add your Base path e.g. /top-10-products

  • Add the Target e.g. https://api.tinybird.co/v0/pipes/top-10-products.json?token=p.eyJ1Ijog...

  • Next

  • Select Pass through for security

  • Next

  • Choose an Environment to deploy the API to

  • Deploy, and test the API

You can find more information about applying a custom domain name to Apigee here.

Grafbase Edge Gateway

Grafbase allows you to create a centralised GraphQL API layer over many source of data. You can use Grafbase with Tinybird to abstract your API Endpoints & Auth Tokens, taking advantage of Grafbase’s query & auth layer.

To create a new Grafbase Edge Gateway using the Grafbase CLI, the steps are as follows:

Inside a new directory, run:

npx grafbase init --template openapi-tinybird

In Tinybird, open your API Endpoint page. Click the Share Docs button in the top right, then click the OpenAPI 3.0 tab. Copy the shareable link shown, including the full Auth Token.

Create a .env file using the below template and enter the required details.

# TINYBIRD_API_URL is the URL for your published API Endpoint
TINYBIRD_API_URL=
# TINYBIRD_API_TOKEN is the Auth Token with READ access to the API Endpoint
TINYBIRD_API_TOKEN=
# TINYBIRD_API_SCHEMA is the OpenAPI 3.0 spec URL copied from the API Endpoint docs page
TINYBIRD_API_SCHEMA=

You can now run the Grafbase Edge Gateway locally:

npx grafbase dev

Open the local Pathfinder at http://127.0.0.1:4000 to test your Edge Gateway.

Here is an example GraphQL query:

Make sure to replace topPages with the name of your API Endpoint.

query Tinybird {
    tinybird {
        topPages {
            data {
                action
                payload
            }
            rows
        }
    }
}

NGINX

NGINX is a popular web server, reverse proxy, load balancer, mail proxy and HTTP cache. It can be used to create your own API Gateway by passing requests through to your Tinybird API Endpoints. You can self-host NGINX either on-prem or on any public cloud.

You can read more about using NGINX as an API Gateway here.

Below is an example NGINX configuration file that will handle a GET request, and make the request to Tinybird on the user’s behalf. The Auth Token used is only accessed server-side and never exposed to the user.

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    server {
        listen       8080;
        server_name  localhost;
        location /top-10-products {
                proxy_pass https://api.tinybird.co/v0/pipes/top-10-products.json?token=p.eyJ1Ijog...;
        }
    }
}

Errors and retries

When implementing an API Gateway, you must take care to handle potential errors and implement retry strategies where appropriate.

Read more about API Endpoint error codes..

In general, there are two error codes where automatic retries should be implemented:

  • HTTP429: Too many requests

  • HTTP500: Internal Server Error

Retrying these requests should follow an exponential backoff.