From d1b9ba7a2a79ce0cf44d61bc008144e17fcbdfeb Mon Sep 17 00:00:00 2001 From: Paul Copplestone Date: Mon, 12 Apr 2021 18:07:22 +0800 Subject: [PATCH] Adds docs for the API --- web/docs/guides/api.mdx | 264 ++++++++++++++++++++++++++++++++++++ web/docs/guides/storage.mdx | 2 +- web/sidebars.js | 1 + 3 files changed, 266 insertions(+), 1 deletion(-) create mode 100644 web/docs/guides/api.mdx diff --git a/web/docs/guides/api.mdx b/web/docs/guides/api.mdx new file mode 100644 index 00000000000..f9a739fec23 --- /dev/null +++ b/web/docs/guides/api.mdx @@ -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. + + + + +```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". +``` + + + + + +```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) +); +``` + + + + + +### 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. + + + + +```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. +``` + + + + + + +#### 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. + + + + +```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. +``` + + + + + +### 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: + + + + + +```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('*') +``` + + + + +```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" +``` + + + + +#### 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. + + + + +```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. +``` + + + + +```bash +alter publication supabase_realtime add table products; +``` + + + + +#### 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 + + + + +```sh +1. Go to the "Authentication" section. +2. Click on "Policies" in the sidebar. +3. Click on the Padlock to enable Row Level Security. +``` + + + + +```bash +alter table todos enable row level security; +``` + + + + + +#### 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). \ No newline at end of file diff --git a/web/docs/guides/storage.mdx b/web/docs/guides/storage.mdx index 9f8c91c63bf..c6e29eddf4f 100644 --- a/web/docs/guides/storage.mdx +++ b/web/docs/guides/storage.mdx @@ -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. diff --git a/web/sidebars.js b/web/sidebars.js index 9907e797dc7..ec9f6644e21 100755 --- a/web/sidebars.js +++ b/web/sidebars.js @@ -73,6 +73,7 @@ module.exports = { 'guides/database', 'guides/auth', 'guides/storage', + 'guides/api', 'guides/client-libraries', 'guides/local-development', 'guides/self-hosting',