Sharing endpoints documentation


In this guide you'll learn better ways of sharing your API Endpoints documentation with development teams.

The Tinybird API Endpoint page

In Tinybird, when publishing an API Endpoint, we generate a documentation page for you that is ready to share and OpenAPI 3.0 compatible. This page contains your API Endpoint description, information about the dynamic parameters you can use when querying this endpoint, and code snippets for quickly integrating your API in your 3rd party applications.

Once your API Endpoint is ready, sharing it is as easy as going to the documentation view and clicking on the share link that sits on top of the page.

Also, as a creator of an API Endpoint, you will see the main performance indicators and have access to the API Endpoint request log, all from this page. This turns out to be very useful for detecting errors or performance degradation periods in your API Endpoints.

The API Endpoint page changes dynamically as you do changes in your Pipe

Note also that the public API Endpoint page is designed using the OpenAPI 3.0 standard, so, from the share modal window, you will be able to get an OpenAPI url that you can use in any compatible system such as Swagger or Postman.

Using Auth Tokens to define API Endpoint subsets

As you might already know, Tinybird authentication is based on Auth tokens which contain different scopes for specific resources. An Auth token lets you, for example, read from one or many API Endpoints, or get write permissions for a particular Data Source.

Well, if you take a closer look at the URLs we generate for sharing a public API Endpoint page, you will see that after the Endpoint Id, it includes the token parameter. This means that this page is only accessible if the auth token provided in the URL has read permissions for it.

Security goes first:

Tinybird automatically generates a read-only Auth Token when sharing a public API endpoint page for the first time. If you don't do it on purpose, your admin token won't ever get exposed.

The API Endpoints list page

Tinybird also allows you to render the API Endpoints information for a given token.

By using the URL pattern shown above, your browser will show you a list page that shows all API Endpoints which that token can read from.

The API Endpoints list page is extremely useful for sharing your API Endpoint documentation with development teams

When integrating your API Endpoint in your applications we highly recommend that you manage dedicated auth tokens. The easiest way is probably creating an Auth Token for every application environment, so that you can also track the different requests to your API Endpoints by application, and choose which API Endpoints are accessible for them.

Once you do that, you will be able to share auto-generated documentation with ease without compromising your data privacy and security.

Look at your share modal:

Although we create a read token by default when sharing an API Endpoint documentation page, in the Share modal window you can also see public URLs for every Auth Token with read permissions for your Pipe.

Browsing your docs in Swagger

As mentioned above, all our documentation is compatible with OpenAPI 3.0 and accessible via API. A quick way of generating documentation in Swagger is just using the OpenAPI 3.0 URL you can find in the share modal window (under the OpenAPI 3.0 tab) and use it on your prefered Swagger installation.

You can generate as many URLs as you need by using different Auth Tokens

If you use an Auth Token with permissions for more than one API Endpoint, the Swagger documentation will contain information about all the API Endpoints at once.