Data retrieval from your SQL tables can be easily accomplished by hitting a REST endpoint that includes your table name and any number of filter query parameters. Sending a network request to the route will then construct a SQL query that grabs only the data your route is requesting.

Request Structure

Every request is simple and standardized in how you interact with a table resource in your database. Follow the below rules and see the example at the bottom for how to apply it to your use case.

Authorization Headers

Every request sent to a StarbaseDB instance must pass in an Authorization Bearer token with a token value matching the value defined in your wrangler.toml file where the variable name is AUTHORIZATION_TOKEN. For any request that does not have a matching token value, the request will automatically be denied and cannot pass into the storage layer of your database.

An example cURL including the Bearer token can be seen below.

curl --location 'https://starbasedb.YOUR-IDENTIFIER.workers.dev/rest/your_table_name' \
--header 'Authorization: Bearer ABC123' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'Content-type=application/json'

Route

Retrieving objects from your database table happens via an HTTP GET request with a route of /rest/{YOUR_TABLE_NAME}.

YOUR_TABLE_NAME can be replaced with any table name in your database

Query Params

Reference the Filter Parameters section below for a comprehensive list of query parameters you can append onto the route for additional filtering, sorting and ordering logic. Any number of query parameters can be used with one another. Here is an example of multiple in action at once.

curl --location --request GET 'https://starbasedb.{YOUR-IDENTIFIER}.workers.dev/lite/users?name.in=Alice%2CBob&user_id.gte=0&email.like=%25example.com&sort_by=user_id&order=DESC&limit=10&offset=0' \
--header 'Authorization: Bearer ABC123' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'Content-type=application/json'

Filter Parameters

We allow for query params at the end of the routes, particularly for the Retrieve Resource endpoint, so you can narrow down the results that are returned back to you. Below is a list of these query params and an example for each.

You can combine multiple query params to get more granular filtering!

Operation	Example
Equals	`/rest/users?name=”Alice”`
Not Equals	`/rest/users?name.ne=”Alice”`
Like	`/rest/users?name.like=”Al%25”`
In	`/rest/users?name.in=”Alice,Bob”`
Greater Than	`/rest/users?user_id.gt=0`
Greater Than or Equal	`/rest/users?user_id.gte=1`
Less Than	`/rest/users?user_id.lt=100`
Less Than or Equal	`/rest/users?user_id.lte=99`
Sort By	`/rest/users?sort_by=user_id`
Order	`/rest/users?order=DESC`
Limit	`/rest/users?limit=10`
Offset	`/rest/users?offset=10`

Example

Use the below example to get started.

curl --location --request GET 'https://starbasedb.YOUR-IDENTIFIER.workers.dev/rest/users?name.ne="Alice"' \
--header 'Authorization: Bearer ABC123' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'Content-type=application/json'