From e3a943e12d86b67be016ffc63057b1561bdbc5c2 Mon Sep 17 00:00:00 2001 From: Oliver Rice Date: Wed, 5 Apr 2023 10:56:42 -0500 Subject: [PATCH 1/8] API docs update --- README.md | 3 ++- apps/docs/pages/guides/database/api.mdx | 28 ++++++++++++++++++------- 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index f4c8b99e41f..0ae54fc8d0b 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,8 @@ - [x] Authentication and Authorization. [Docs](https://supabase.com/docs/guides/auth) - [x] Auto-generated APIs. - [x] REST. [Docs](https://supabase.com/docs/guides/database/api#rest-api) + - [x] GraphQL. [Docs](https://supabase.com/docs/guides/database/api#graphql-api) - [x] Realtime subscriptions. [Docs](https://supabase.com/docs/guides/database/api#realtime-api) - - [x] GraphQL (Beta). [Docs](https://supabase.com/docs/guides/database/api#graphql-api) - [x] Functions. - [x] Database Functions. [Docs](https://supabase.com/docs/guides/database/functions) - [x] Edge Functions [Docs](https://supabase.com/docs/guides/functions) @@ -63,6 +63,7 @@ You can also [self-host](https://supabase.com/docs/guides/hosting/overview) and - [PostgreSQL](https://www.postgresql.org/) is an object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance. - [Realtime](https://github.com/supabase/realtime) is an Elixir server that allows you to listen to PostgreSQL inserts, updates, and deletes using websockets. Realtime polls Postgres' built-in replication functionality for database changes, converts changes to JSON, then broadcasts the JSON over websockets to authorized clients. - [PostgREST](http://postgrest.org/) is a web server that turns your PostgreSQL database directly into a RESTful API +- [pg_graphql](http://github.com/supabase/pg_graphql/) a PostgreSQL extension that exposes a GraphQL API - [Storage](https://github.com/supabase/storage-api) provides a RESTful interface for managing Files stored in S3, using Postgres to manage permissions. - [postgres-meta](https://github.com/supabase/postgres-meta) is a RESTful API for managing your Postgres, allowing you to fetch tables, add roles, and run queries, etc. - [GoTrue](https://github.com/netlify/gotrue) is an SWT based API for managing users and issuing SWT tokens. diff --git a/apps/docs/pages/guides/database/api.mdx b/apps/docs/pages/guides/database/api.mdx index fc8f86a18ae..4b83ce2a50d 100644 --- a/apps/docs/pages/guides/database/api.mdx +++ b/apps/docs/pages/guides/database/api.mdx @@ -12,7 +12,7 @@ Supabase auto-generates three types of API directly from your database schema. - REST - interact with your database through a restful interface. - Realtime - listen to database changes. -- GraphQL - [in beta](https://supabase.com/blog/pg-graphql). +- GraphQL - manipulate your database using a graph-like query language The APIs are: @@ -25,9 +25,10 @@ The APIs are: ## REST API [#rest-api-overview] Supabase provides a RESTful API using [PostgREST](https://postgrest.org/). This is a very thin API layer on top of Postgres. -It provides everything you need from a CRUD API: +It provides everything you need from a CRUD API at the URL `https://.supabase.co/rest/v1/`. -- Basic CRUD operations +Features: +- Basic CRUD operations (Create/Read/Update/Delete) - Deeply nested joins, allowing you to fetch data from multiple tables in a single fetch - Works with Postgres Views - Works with Postgres Functions @@ -42,15 +43,28 @@ It provides everything you need from a CRUD API: > +Reference: +- [Docs](https://postgrest.org/) +- [Source Code](https://github.com/PostgREST/postgrest) + ## GraphQL API [#graphql-api-overview] - +Supabase uses [pg_graphql](https://supabase.github.io/pg_graphql/) to expose a GraphQL API endpoint at `https://.supabase.co/graphql/v1/`. +You can introspect and query the GraphQL API of an existing Supabase project within Studio [here](https://app.supabase.com/project/_/api/graphiql), +or navigate there manually at `API Docs > GraphQL > GraphiQL`. -GraphQL is in Beta, and may have breaking changes. It is only available on self-hosted setups and Supabase projects created after 28th March 2022. +The GraphQL interface is automatically reflected from your database's schema and supports: +- Basic CRUD operations (Create/Read/Update/Delete) +- Support for Tables, Views, Materialized Views, and Foreign Tables +- Arbitrarily deep relationships among tables/views +- User defined computed fields +- The Postgres security model - including Row Level Security, Roles, and Grants. - +The GraphQL API resolves all requests in a single round-trip leading to fast response times and high throughput. -GraphQL in Supabase works through [pg_graphql](https://supabase.com/blog/pg-graphql), an open source PostgreSQL extension for GraphQL. +Reference: +- [Docs](https://supabase.github.io/pg_graphql/) +- [Source Code](https://github.com/supabase/pg_graphql) ## Realtime API [#realtime-api-overview] From 5d6416bc2a23ac569404d1df03d2577b16593d9a Mon Sep 17 00:00:00 2001 From: Oliver Rice Date: Wed, 5 Apr 2023 12:31:14 -0500 Subject: [PATCH 2/8] Accepted: PostgREST materialized views, foreign tables Co-authored-by: Steve Chavez --- apps/docs/pages/guides/database/api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/pages/guides/database/api.mdx b/apps/docs/pages/guides/database/api.mdx index 4b83ce2a50d..1783a69064c 100644 --- a/apps/docs/pages/guides/database/api.mdx +++ b/apps/docs/pages/guides/database/api.mdx @@ -30,7 +30,7 @@ It provides everything you need from a CRUD API at the URL `https:// Date: Wed, 5 Apr 2023 12:31:30 -0500 Subject: [PATCH 3/8] Accepted: PostgREST arbitrary depth joins Co-authored-by: Steve Chavez --- apps/docs/pages/guides/database/api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/pages/guides/database/api.mdx b/apps/docs/pages/guides/database/api.mdx index 1783a69064c..18c36927503 100644 --- a/apps/docs/pages/guides/database/api.mdx +++ b/apps/docs/pages/guides/database/api.mdx @@ -29,7 +29,7 @@ It provides everything you need from a CRUD API at the URL `https:// Date: Wed, 5 Apr 2023 12:31:55 -0500 Subject: [PATCH 4/8] Accepted: PostgREST requests resolve to single statement Co-authored-by: Steve Chavez --- apps/docs/pages/guides/database/api.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/apps/docs/pages/guides/database/api.mdx b/apps/docs/pages/guides/database/api.mdx index 18c36927503..ce21be24c25 100644 --- a/apps/docs/pages/guides/database/api.mdx +++ b/apps/docs/pages/guides/database/api.mdx @@ -34,6 +34,8 @@ Features: - Works with Postgres Functions - Works with the Postgres security model - including Row Level Security, Roles, and Grants. +The REST API resolves all requests to a single SQL statement leading to fast response times and high throughput. +
+
+ +Reference: +- [Docs](https://postgrest.org/) +- [Source Code](https://github.com/PostgREST/postgrest) + ## GraphQL API [#graphql-api-overview] -GraphQL in Supabase works through [pg_graphql](https://supabase.com/blog/pg-graphql), an open source PostgreSQL extension for GraphQL. +Supabase uses [pg_graphql](https://supabase.github.io/pg_graphql/) to expose a GraphQL API endpoint at `https://.supabase.co/graphql/v1/`. +You can introspect and query the GraphQL API of an existing Supabase project within Studio [here](https://app.supabase.com/project/_/api/graphiql), +or navigate there manually at `API Docs > GraphQL > GraphiQL`. + +The GraphQL interface is automatically reflected from your database's schema and supports: +- Basic CRUD operations (Create/Read/Update/Delete) +- Support for Tables, Views, Materialized Views, and Foreign Tables +- Arbitrarily deep relationships among tables/views +- User defined computed fields +- The Postgres security model - including Row Level Security, Roles, and Grants. + +The GraphQL API resolves all requests in a single round-trip leading to fast response times and high throughput. + +Reference: +- [Docs](https://supabase.github.io/pg_graphql/) +- [Source Code](https://github.com/supabase/pg_graphql) ## Realtime API [#realtime-api-overview] diff --git a/apps/docs/pages/guides/database/api.mdx b/apps/docs/pages/guides/database/api.mdx deleted file mode 100644 index c85651b0e16..00000000000 --- a/apps/docs/pages/guides/database/api.mdx +++ /dev/null @@ -1,421 +0,0 @@ -import Layout from '~/layouts/DefaultGuideLayout' - -export const meta = { - id: 'api', - title: 'Serverless APIs', - description: 'Auto-generating and Realtime APIs.', - sidebar_label: 'Overview', - video: 'https://www.youtube.com/v/rPAJJFdtPw0', -} - -Supabase auto-generates three types of API directly from your database schema. - -- REST - interact with your database through a restful interface. -- Realtime - listen to database changes. -- GraphQL - manipulate your database using a graph-like query language - -The APIs are: - -- **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. - -## REST API [#rest-api-overview] - -Supabase provides a RESTful API using [PostgREST](https://postgrest.org/). This is a very thin API layer on top of Postgres. -It provides everything you need from a CRUD API at the URL `https://.supabase.co/rest/v1/`. - -The REST interface is automatically reflected from your database's schema and supports: -- Basic CRUD operations (Create/Read/Update/Delete) -- Arbitrarily deep relationships among tables/views, functions that return table types can also nest related tables/views. -- Works with Postgres Views, Materialized Views and Foreign Tables -- Works with Postgres Functions -- User defined computed columns and computed relationships -- Works with the Postgres security model - including Row Level Security, Roles, and Grants. - -The REST API resolves all requests to a single SQL statement leading to fast response times and high throughput. - -
- -
- -Reference: -- [Docs](https://postgrest.org/) -- [Source Code](https://github.com/PostgREST/postgrest) - -## GraphQL API [#graphql-api-overview] - -Supabase uses [pg_graphql](https://supabase.github.io/pg_graphql/) to expose a GraphQL API endpoint at `https://.supabase.co/graphql/v1/`. -You can introspect and query the GraphQL API of an existing Supabase project within Studio [here](https://app.supabase.com/project/_/api/graphiql), -or navigate there manually at `API Docs > GraphQL > GraphiQL`. - -The GraphQL interface is automatically reflected from your database's schema and supports: -- Basic CRUD operations (Create/Read/Update/Delete) -- Support for Tables, Views, Materialized Views, and Foreign Tables -- Arbitrarily deep relationships among tables/views -- User defined computed fields -- The Postgres security model - including Row Level Security, Roles, and Grants. - -The GraphQL API resolves all requests in a single round-trip leading to fast response times and high throughput. - -Reference: -- [Docs](https://supabase.github.io/pg_graphql/) -- [Source Code](https://github.com/supabase/pg_graphql) - -## Realtime API [#realtime-api-overview] - -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. -Go to your project's [Replication section](https://app.supabase.com/project/_/database/replication) to get started. - -## Getting started - -All APIs are auto-created from Database tables. After you have added tables or functions to your database, you can use the APIs provided. - -### 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` to store tasks. -This creates a corresponding route `todos` which can accept `GET`, `POST`, `PATCH`, & `DELETE` requests. - - - - -1. Go to the [Table editor](https://app.supabase.com/project/_/editor) page in the Dashboard. -1. Click **New Table** and create a table with the name `todos`. -1. Click **Save**. -1. Click **New Column** and create a column with the name `task` and type `text`. -1. 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. - -1. Go to the [Settings](https://app.supabase.com/project/_/settings/general) page in the Dashboard. -2. Click **API** in the sidebar. -3. Find your API `URL`, `anon`, and `service_role` keys on this page. - - - -The REST API and the GraphQL API are both accessible through this URL: - -- REST: `https://.supabase.co/rest/v1` -- GraphQL: `https://.supabase.co/graphql/v1` - -Both of these routes require the `anon` key to be passed through an `apikey` header. - -#### API Keys - -You are provided with two keys: - -- 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. NEVER use this key in a browser. - -### Accessing the docs in the Dashboard - -#### REST API [#rest-api-dashboard-docs] - -Supabase generates documentation in the [Dashboard](https://app.supabase.com) which updates as you make database changes. -Let's view the documentation for a `countries` table which we created in our database. - -1. Go to the [API](https://app.supabase.com/project/_/api) page in the Dashboard. -2. Find the `countries` table under **Tables and Views** in the sidebar. -3. Switch between the JavaScript and the cURL docs using the tabs. - - - -#### GraphQL - -The GraphQL Endpoint that we provide (`https://.supabase.co/graphql/v1`) is compatible with any GraphiQL implementation that can pass an `apikey` header. -Some suggested applications: - -- [paw.cloud](https://paw.cloud) -- [insomnia.rest](https://insomnia.rest) -- [postman.com/graphql](https://www.postman.com/graphql/) -- Self-hosted GraphiQL: GraphiQL can be served through a simple HTML file. See [this discussion](https://github.com/supabase/supabase/discussions/6144) for more details. - -## Using the API - -### REST API - -You can interact with your API directly via HTTP requests, 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 -const { 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 '/rest/v1/todos' \ --H "apikey: " \ --H "Authorization: Bearer " -``` - - - - -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). - -### GraphQL API - -You can use any GraphQL client with the Supabase GraphQL API. For our GraphQL example we will use [urql](https://formidable.com/open-source/urql/docs/). - - - - -```javascript -import { createClient, useQuery } from 'urql' - -// Prepare API key and Authorization header -const headers = { - apikey: , - authorization: `Bearer ${}`, -} - -// Create GraphQL client -// See: https://formidable.com/open-source/urql/docs/basics/react-preact/#setting-up-the-client -const client = createClient({ - url: '/graphql/v1', - fetchOptions: function createFetchOptions() { - return { headers } - }, -}) - -// Prepare our GraphQL query -const TodosQuery = ` - query { - todosCollection { - edges { - node { - id - title - } - } - } - } -` - -// Query for the data (React) -const [result, reexecuteQuery] = useQuery({ - query: TodosQuery, -}) - -// Read the result -const { data, fetching, error } = result -``` - - - - -```bash -# Append /graphql/v1/ to your URL, and then use the table name as the route -curl --request POST '/graphql/v1' \ --H 'apikey: ' \ --H 'Authorization: Bearer ' \ --H 'Content-Type: application/json' \ --d '{ "query":"{ todos(first: 3) { edges { node { id } } } }" }' -``` - - - - -### Realtime API - -By default Realtime is disabled on your database. Let's turn on Realtime for the `todos` table. - - - - -1. Go to the [Database](https://app.supabase.com/project/_/database/tables) page in the Dashboard. -2. Click on **Replication** in the sidebar. -3. Control which database events are sent by toggling **Insert**, **Update**, and **Delete**. -4. Control which tables broadcast changes by selecting **Source** and toggling each table. - - - - - - -```sql -alter publication supabase_realtime add table todos; -``` - - - - -From the client, we can listen to any new data that is inserted into the `todos` table: - -```javascript -// Initialize the JS client -import { createClient } from '@supabase/supabase-js' -const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY) - -// Create a function to handle inserts -const handleInserts = (payload) => { - console.log('Change received!', payload) -} - -// Listen to inserts -const { data: todos, error } = await supabase.from('todos').on('INSERT', handleInserts).subscribe() -``` - -Use [subscribe()](/docs/reference/javascript/subscribe) to listen to database changes. -The Realtime API works through PostgreSQL's replication functionality. Postgres sends database changes to a [publication](/docs/guides/database/replication#publications) -called `supabase_realtime`, and by managing this publication you can control which data is broadcast. - -## API Security - -### Securing your Routes - -Your API is designed to work with Postgres Row Level Security (RLS). 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](/docs/guides/auth#policies). -When you create a table in Postgres, Row Level Security is disabled by default. To enable RLS: - - - - -1. Go to the [Authentication](https://app.supabase.com/project/_/auth/users) page in the Dashboard. -2. Click on **Policies** in the sidebar. -3. Select **Enable RLS** to enable Row Level Security. - - - - -```sql -alter table todos enable row level security; -``` - - - - -### The `service_role` key - -Never expose the `service_role` key in a browser or anywhere where a user can see it. This Key is designed to bypass Row Level Security - so it should only be used on a private server. - -A common use case for the `service_role` key is to run data analytics jobs on the backend. To support joins on user id, it is often useful to grant the service role read access to `auth.users` table. - -```sql -grant select on table auth.users to service_role; -``` - -We have [partnered with GitHub](https://github.blog/changelog/2022-03-28-supabase-is-now-a-github-secret-scanning-partner/) to scan for Supabase `service_role` keys pushed to public repositories. -If they detect any keys with service_role privileges being pushed to GitHub, they will forward the API key to us, so that we can automatically revoke the detected secrets and notify you, protecting your data against malicious actors. - -### Safeguards towards accidental deletes and updates - -For all projects, by default, the Postgres extension [safeupdate](https://github.com/eradman/pg-safeupdate) is enabled for all queries coming from the API. -This ensures that any `delete()` or `update()` would fail if there are no accompanying filters provided. -To confirm that safeupdate is enabled for queries going through the API of your project, the following query could be run: - -```sql -select usename,useconfig from pg_shadow where usename = 'authenticator' ; -``` - -The expected value for `useconfig` should be: - -```sql -['session_preload_libraries=supautils, safeupdate'] -``` - -export const Page = ({ children }) => - -export default Page From 98e0563c33e3442c33b4c567c1143a5c0014a2aa Mon Sep 17 00:00:00 2001 From: Oliver Rice Date: Thu, 6 Apr 2023 15:13:25 -0500 Subject: [PATCH 8/8] revert video and minor language tweaks to later version --- apps/docs/pages/guides/api.mdx | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/apps/docs/pages/guides/api.mdx b/apps/docs/pages/guides/api.mdx index 2f0db1f7c24..3b518ced47b 100644 --- a/apps/docs/pages/guides/api.mdx +++ b/apps/docs/pages/guides/api.mdx @@ -10,11 +10,15 @@ export const meta = { Supabase auto-generates three types of API directly from your database schema. -- REST - interact with your database through a restful interface. +- REST - connect to your database through a restful interface, directly from the browser. - GraphQL - manipulate your database using a graph-like query language. - Realtime - listen to database changes. -The APIs are: +All the APIs are auto-generated from your database and are designed to get you building as fast as possible, without writing a single line of code. + +You can use them directly from the browser (two-tier architecture), or as a complement to your own API server (three-tier architecture). + +## Features - **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. @@ -37,15 +41,6 @@ The REST interface is automatically reflected from your database's schema and su The REST API resolves all requests to a single SQL statement leading to fast response times and high throughput. -
- -
- Reference: - [Docs](https://postgrest.org/) - [Source Code](https://github.com/PostgREST/postgrest)