The API Endpoints tab (beta)

Creating REST endpoints from saved queries

The API Endpionts tab (currently in beta) lets you create ClickHouse® Query API Endpoints that let you invoke queries via REST.

When you first use this tab, you won’t have any API endpoints:

Figure 1 - The API Endpoints tab

Defining a simple endpoint

Click the button to create an API endpoint. You’ll see this dialog:

Figure 2 - No endpoints defined

As an example, we’ll define a new endpoint named /maddie that has a simple query. It returns four fields from the page_views table:

Figure 3 - Defining a simple endpoint

Click the button to save the endpoints and return to the API Endpoints tab:

Figure 4 - One simple endpoint defined

It may take 30 seconds until your ClickHouse cluster’s configuration is updated to support the new endpoint. If you click the button before the configuration is updated, you’ll see this error message:

Figure 5 - Cluster configuration not updated yet

When things are updated, clicking the button displays the results of the query:

Figure 6 - Query results

Defining an endpoint with a parameter

You can define parameters for your query, as you would expect, using the syntax {name:format}. This query defines a parameter named country of datatype String:

Figure 7 - A query with a parameter

Notice that when the new query is selected, the UI has an entry field for each parameter. In Figure 7 above, we’re using the value USA for the country parameter. Clicking the button gives the results you’d expect:

Figure 8 - Query results with a parameter specified

Invoking an endpoint from outside the ACM

This is all well and good, but the point of defining API endpoints is to let your applications run ClickHouse queries without building those queries themselves. As an example, we’ll get our cluster’s connection information from the Cluster Connection Details dialog, then use curl to invoke our simple query above:

curl https://admin:PASSWORD@clustername.altinity-maddie-byok.altinity.cloud:8443/maddie

This request returns the data we’d expect:

/home	direct	desktop	Germany
/contact	direct	desktop	India
/products	google.com	tablet	Canada
/checkout	facebook.com	mobile	USA
/cart	direct	desktop	Australia
/home	google.com	mobile	USA
/products	facebook.com	desktop	Canada
/cart	twitter.com	tablet	UK
/checkout	google.com	mobile	USA
/blog	twitter.com	desktop	Australia

Of course, if you’re creating API Endpoints for applications, you may want to add FORMAT JSON or something similar to your SQL statements.

For more information about ways to connect to your cluster, see the Cluster Connection Details dialog. As you develop applications using your API Endpoints, the ClickHouse documentation for Query API Endpoints is also a useful reference.