mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 17:35:10 +03:00
Adds docs for the API
This commit is contained in:
Paul Copplestone committed
1 parent
b473e95d71
commit
d1b9ba7a2a
3 files changed
+266
-1
No files matched your search
@@ -0,0 +1,264 @@
|
||||
---
|
||||
id: api
|
||||
title: APIs
|
||||
description: Auto-generating and Realtime APIs.
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
Supabase generates APIs directly from your Database schema. The API is:
|
||||
|
||||
- Instant and auto-generated: as you update your database the changes are immediately accessible through your API.
|
||||
- Self documenting: Supabase generates documentation in the Dashboard which updates as you make database changes.
|
||||
- Secure: the API is configured to work with PostgreSQL's Row Level Security, provisioned behind an API gateway with key-auth enabled.
|
||||
- Fast: our benchmarks for basic reads are more than 300% faster than Firebase. The API is a very thin layer on top of Postgres, which does most of the heavy-lifting.
|
||||
- Scalable: the API can serve thousands of simultaneous requests, and works well for Serverless workloads.
|
||||
|
||||
|
||||
### RESTful API
|
||||
|
||||
Supabase provides a RESTful API using [PostgREST](postgrest.org/). This is a very thin API layer on top of Postgres.
|
||||
It provides everything you need from a CRUD API:
|
||||
|
||||
- Basic CRUD opertations
|
||||
- Deeply nested joins, allowing you to fetch data from multiple tables in a single fetch
|
||||
- Works with Postgres Views
|
||||
- Works with Postgres Functions
|
||||
- Works with the Postgres security model - including Row Level Security, Roles, and Grants.
|
||||
|
||||
|
||||
### Realtime API
|
||||
|
||||
Supabase provides a Realtime API using [Realtime](https://github.com/supabase/realtime). You can use this to listen to database changes over websockets.
|
||||
Realtime leverages PostgreSQL's built-in logical replication. You can manage your Realtime API simply by managing Postgres publications.
|
||||
|
||||
|
||||
## Getting started
|
||||
|
||||
After you have added tables or functions to your database, you can use the API.
|
||||
|
||||
### Creating API Routes
|
||||
|
||||
API routes are automatically created when you create Postgres Tables, Views, or Functions.
|
||||
|
||||
Let's create our first
|
||||
API route by creating a table called `todos` (which will store some public user information).
|
||||
This will create a corresponding route `todos` which can accept `GET`, `POST`, `PATCH`, & `DELETE` requests.
|
||||
|
||||
<Tabs
|
||||
defaultValue="UI"
|
||||
values={[
|
||||
{label: 'UI', value: 'UI'},
|
||||
{label: 'SQL', value: 'SQL'},
|
||||
]}>
|
||||
<TabItem value="UI">
|
||||
|
||||
```sh
|
||||
1. Go to the "Table editor" section.
|
||||
2. Click "New Table".
|
||||
3. Enter the table name "todos".
|
||||
4. Click "Save".
|
||||
5. Click "New Column".
|
||||
6. Enter the column name "task" and make the type "text".
|
||||
7. Click "Save".
|
||||
```
|
||||
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="SQL">
|
||||
|
||||
```sql
|
||||
-- Create a table called "todos" with a column to store tasks.
|
||||
|
||||
create table todos (
|
||||
id bigint generated by default as identity primary key,
|
||||
task text check (char_length(task) > 3)
|
||||
);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
### API URL and Keys
|
||||
|
||||
Every Supabase project has a unique API URL. Your API is secured behind an API gateway which requires an API Key for every request.
|
||||
|
||||
You can find the Keys inside the Dashboard.
|
||||
|
||||
<Tabs
|
||||
defaultValue="UI"
|
||||
values={[
|
||||
{label: 'UI', value: 'UI'}
|
||||
]}>
|
||||
<TabItem value="UI">
|
||||
|
||||
```sh
|
||||
1. Go to the "Settings" section.
|
||||
2. Click "API" in the sidebar.
|
||||
3. Find your API URL in this page.
|
||||
4. Find your "anon" and "service_role" keys on this page.
|
||||
```
|
||||
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
#### Details and links:
|
||||
|
||||
You are provided with two keys initially:
|
||||
|
||||
- an `anon` key, which is safe to be used in a browser context.
|
||||
- a `service_role` key, which should only be used on a server. This key can bypass Row Level Security.
|
||||
|
||||
|
||||
### Accessing the Docs
|
||||
|
||||
Supabase generates documentation in the Dashboard which updates as you make database changes.
|
||||
|
||||
Let's view the documentation for the `todos` table which we created in the first step.
|
||||
|
||||
<Tabs
|
||||
defaultValue="UI"
|
||||
values={[
|
||||
{label: 'UI', value: 'UI'}
|
||||
]}>
|
||||
<TabItem value="UI">
|
||||
|
||||
```sh
|
||||
1. Go to the "API" section.
|
||||
2. Find "todos" in the "Tables an Views" section.
|
||||
3. Switch between the Javascript and the cURL docs using the tabs.
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
### Using the API
|
||||
|
||||
You can interact with your API directly via HTTP reqeusts, or you can use the client libraries which we provide.
|
||||
|
||||
Let's see how to make a request to the `todos` table which we created in the first step,
|
||||
using the API URL (`[SUPABASE_URL]`) and Key (`[SUPABASE_ANON_KEY]`) we provided:
|
||||
|
||||
|
||||
<Tabs
|
||||
defaultValue="Javascript"
|
||||
values={[
|
||||
{label: 'Javascript', value: 'Javascript'},
|
||||
{label: 'cURL', value: 'cURL'},
|
||||
]}>
|
||||
<TabItem value="Javascript">
|
||||
|
||||
```javascript
|
||||
// Initialize the JS client
|
||||
import { createClient } from '@supabase/supabase-js'
|
||||
const supabase = createClient([SUPABASE_URL], [SUPABASE_ANON_KEY])
|
||||
|
||||
// Make a request
|
||||
let { data: todos, error } = await supabase
|
||||
.from('todos')
|
||||
.select('*')
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="cURL">
|
||||
|
||||
```bash
|
||||
# Append /rest/v1/ to your URL, and then use the table name as the route
|
||||
curl '[SUPABASE_URL]/rest/v1/todos' \
|
||||
-H "apikey: [SUPABASE_ANON_KEY]" \
|
||||
-H "Authorization: Bearer SUPABASE_ANON_KEY"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
#### Details and links:
|
||||
|
||||
- When you create a table in Postgres, Row Level Security is disabled by default. Make sure you secure it by [enabling RLS](/docs/guides/api#securing-your-routes).
|
||||
- Never expose the `service_role` key in a browser or anywhere where a user can see it.
|
||||
- JS Reference: [select()](/docs/reference/javascript/select),
|
||||
[insert()](/docs/reference/javascript/insert),
|
||||
[update()](/docs/reference/javascript/update),
|
||||
[upsert()](/docs/reference/javascript/upsert),
|
||||
[delete()](/docs/reference/javascript/delete),
|
||||
[rpc()](/docs/reference/javascript/rpc) (call Postgres functions / stored procedures).
|
||||
|
||||
|
||||
### Managing Realtime
|
||||
|
||||
|
||||
The Realtime API works through PostgreSQL's replication functionality. Postgres sends database changes to a "publication"
|
||||
called `supabase_realtime`, and by managing this publication you can control which data is broadcast.
|
||||
|
||||
By default Realtime is disabled on your database. Let's turn on Realtime for the `todos` table.
|
||||
|
||||
<Tabs
|
||||
defaultValue="UI"
|
||||
values={[
|
||||
{label: 'UI', value: 'UI'},
|
||||
{label: 'SQL', value: 'SQL'},
|
||||
]}>
|
||||
<TabItem value="UI">
|
||||
|
||||
```sh
|
||||
1. Go to the "Database" section.
|
||||
2. Click on "Replication" in the sidebar.
|
||||
3. Control which database events are sent by toggling the Insert/Update/Delete toggles.
|
||||
4. Control which tables broadcast changes by clicking into the "Source" and toggling the tables.
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="SQL">
|
||||
|
||||
```bash
|
||||
alter publication supabase_realtime add table products;
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
#### Details and links:
|
||||
|
||||
- You should only turn on realtime for Public tables (where all data should be accessible).
|
||||
- [JS Reference](/docs/reference/javascript/subscribe): Subscribe to database changes using the realtime client
|
||||
|
||||
|
||||
### Securing your Routes
|
||||
|
||||
<Tabs
|
||||
defaultValue="UI"
|
||||
values={[
|
||||
{label: 'UI', value: 'UI'},
|
||||
{label: 'SQL', value: 'SQL'},
|
||||
]}>
|
||||
<TabItem value="UI">
|
||||
|
||||
```sh
|
||||
1. Go to the "Authentication" section.
|
||||
2. Click on "Policies" in the sidebar.
|
||||
3. Click on the Padlock to enable Row Level Security.
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="SQL">
|
||||
|
||||
```bash
|
||||
alter table todos enable row level security;
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
#### Details and links:
|
||||
|
||||
- Your API is designed to work with Postgres Row Level Security. If you use Supabase [Auth](/docs/guides/auth), you can restrict data based on the logged-in user.
|
||||
- To control access to your data, you can use [Policies](http://localhost:3005/docs/guides/auth#policies).
|
||||
@@ -8,7 +8,7 @@ import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
|
||||
## Storage
|
||||
## Overview
|
||||
|
||||
Supabase Storage makes it simple to store and serve large files.
|
||||
|
||||
|
||||
@@ -73,6 +73,7 @@ module.exports = {
|
||||
'guides/database',
|
||||
'guides/auth',
|
||||
'guides/storage',
|
||||
'guides/api',
|
||||
'guides/client-libraries',
|
||||
'guides/local-development',
|
||||
'guides/self-hosting',
|
||||
|
||||
Reference in new issue
Block a user