API Gateways¶
When you publish an API in Tinybird, it is available via api.tinybird.co
or api.us-east.tinybird.co
. These APIs 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 APIs 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 APIs. 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.