API Endpoints¶
The magic of Tinybird is the ability to turn any Pipe into an API Endpoint that you can query immediately.
Ingest your data, build your SQL logic inside a Pipe, and then publish the result of your query as an HTTP API Endpoint.
Once your Pipe is published as an API Endpoint, you can create Tinybird Charts: Interactive, customizable charts of your data.
Read the Concepts > API Endpoints docs for more detail on limits and FAQs.
Create an API Endpoint¶
To create an API Endpoint in Tinybird, you first need to create a Pipe. You can publish any of the queries in your Pipes as an API Endpoint.
Using the UI¶
This section describes how to create an API Endpoint using the UI.
First, create a Pipe in the UI.
On the Pipe view, click the Create API Endpoint
button in the top right of the UI (see Mark 1 below). Then select the Node that you want to publish (see Mark 2 below).
Using the CLI¶
This section describes how to create an API Endpoint using the CLI.
First, create a Pipe in the CLI.
Use the following command to publish an API Endpoint from the CLI. This automatically selects the final Node in the Pipe.
tb pipe publish PIPE_NAME_OR_ID
If you want to manually select a different Node to publish, supply the Node name as the final command argument:
tb pipe publish PIPE_NAME_OR_ID NODE_NAME
Secure your API Endpoints¶
Access to the APIs you publish in Tinybird are also protected with Tokens.
Tokens can have different scopes. This means you can limit which operations a specific Token can do. You can create Tokens that are, for example, only able to do admin operations on Tinybird resources, or only have READ
permission for a specific Data Source.
Read the docs on Tinybird Tokens to understand how they work, and see examples.
API Gateways¶
API Gateways allow you to white label Tinybird API Endpoints to meet additional security & compliance requirements.
When you publish an API Endpoint in Tinybird, it is available via api.tinybird.co
, api.us-east.tinybird.co
, api.eu-central-1.aws.tinybird.co
, api.us-east.aws.tinybird.co
, api.us-west-2.aws.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 Tokens that are managed inside your Tinybird Workspace.
Many users embed these Tinybird URLs directly into their applications using appropriately scoped 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 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:
- Use JSON Web Tokens (JWTs) to enable your application to call Tinybird API Endpoints from the frontend without proxying via your backend.
- Appropriately scope the 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 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 centralized GraphQL API layer over many source of data. You can use Grafbase with Tinybird to abstract your API Endpoints & 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 Create Chart > Share this API Endpoint button in the top right, then click the OpenAPI 3.0 tab. Copy the shareable link shown, including the full 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 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 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.
Token limitations with API Gateways¶
When using an API Gateway or proxy between your application and Tinybird, your proxy will use a Token to auth requests it makes to Tinybird. This Token should be treated as a secret and not exposed to the client.
While this is a popular and useful pattern, it has a few limitations:
- Multi-tenant data access control
- Per-user rate limiting
- Visibility into per-tenant/token usage
These features will need to be developed in your application, or use a service such as Unkey to quickly add multi-tenant API keys, rate limiting, and token usage analytics to your app at scale.
Next steps¶
- Read more about how to use Tokens in the Tokens docs.
- Follow the guide: "Consume APIs in a Next.js frontend with JWTs".