Using the API

Last updated: August 8, 2022

A quick intro into using our API

Using the API

Before we dive in: if you just want the API reference, it's available on our slight.dev site.

Practically all actions you can do on Slight are available through our API. You can create an app, upload a dataset, run an app etc. all from the API. We'll mostly focus on running an app in this quickstart, but it should give you a base to work with the whole API.

Overview of Running an App via the API

In essence, to run an app we need to know:

  • How to identify the app. This can be its ID (e.g. colman/tree_health_statistics_nyc for this app) or its UUID. You can find this on the app's page for example (the URL is partially made from the ID).
  • What values we want to use for the variables. E.g. if the app is parametrized by a start date variable and an end date variable, we need to decide what dates to actually use.

Further, we will normally want to authenticate, although this is optional in the public version. And if we want to limit the number of results, we can do that too.

Let's run a quick example that uses a single variable. We'll run Popularity of a given first name by year; we won't focus a lot on the details of the app for this doc. Let's assume we want to run it with the name Maya. Our API is hosted at api.slightdata.com, so using cURL, we can run it like so:

Loading...

Try running this locally, or pipe it through e.g. jq for nicer output. You'll see that you get back the columns as an array of objects, and the rows as an array of row arrays, each the same length as the number of columns.

Note: this isn't using authentication. We'll discuss that below.

Do I Have to Write the Whole Thing?

No — navigate to an app's page, and click on the API tab. You'll see a runnable example API call generated for you, in one of four langauge options. It will update live to match the values currently set for your variables, using the default otherwise. This avoids you having to fiddle around to get it to work, and you can test that the API call gives the same result as the web UI.

So putting Maya in as the name gives this for me:

Screenshot of the bottom half of the app page, with the API tab open. It shows a token value `slightpat_SOME_TOKEN_HERE` in an input field, and an example API call the same as we see above, but here with the Authorization header added

This is the same as the example in the above section, except it uses a (non-working) token for authentication. Deleting the fourth line (removing authentication) gives the exact same thing as that example.

How Do I Authenticate?

The easiest way to authenticate is to generate a Personal Access Token, or PAT for short. You can see in the above screenshot we've used slightpat_SOME_TOKEN_HERE as a placeholder. You'll want to replace this with a real PAT. Once you fill in the input, it'll change in the example.

We'll add more docs on those in the future. For now, you can generate a PAT by navigating to your settings page while logged in (https://slight.run/settings or click on your avatar in the top right). You'll see a section called Personal Access Tokens:

Screenshot of the section in `/settings` where you can generate a token.

Open the creation modal by clicking on "Create Token". To run an app, make sure to give it "Run an App" (run) permissions at least. After you create the token, you'll get the chance to copy it (until you close the tab):

Screenshot of the Personal Access Tokens section of the `/settings` page, with a newly generated token, and the option to copy it presented.

Fill this in anywhere you need a PAT: while inserting a value into the input in the API tab, or e.g. in the reference doc for running an app.

Finally, you can also generate a new token directly from the API tab too. You can see in the screenshot above (or by navigating to an app's API tab) that there's a button with a + symbol. This opens the same modal as the PAT box in settings.

Do I Have to Specify the bind Field

In our examples, you see that the variable_values element is an array, and each value is an object in which you give the name and value of the variable to specify. You can also optionally supply another field called bind. The possible values are "bound", "raw", or you can just leave it unset.

To learn about the differences, see our section on "Bound or Raw?" in the doc page on variables.

So when do you have to set it?

  • If the variable value can be either bound or raw (bound_allow_raw), you should specify it. If not, it'll default to bound.
  • If the variable is a category variable, it's possible to have options that are the same string, but have different bind states. E.g. maybe you have a column called team and you want to let users use that, or use the string "team". Here you should specify which of the two you mean.

Try adding "bind": "bound" (and a comma after Maya) and you can verify the results don't change.