我们将创建一个名为 todos 的数据库表来存储任务。这将创建一个相应的 API 路由 /rest/v1/todos，该路由可以接收 GET， POST， PATCH， 和 DELETE 请求。

开始使用

所有的API都是由数据库表自动创建的。在你向数据库添加了表或函数后，你可以使用所提供的API。

创建API路由

当你创建Postgres表、视图或函数时，会自动创建API路由。

让我们通过创建一个叫做todos的表来存储任务，来创建我们的第一个API路由。 这将创建一个相应的路由todos，它可以接受GET、POST、PATCH和DELETE请求。

  1. 进入仪表板中的表编辑器页面。
  2. 点击新表，创建一个名为todos的表。
  3. 单击保存。
  4. 点击新列，创建一个名为task的列，类型为text。
  5. 单击保存。
  -- 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和密钥

每个Supabase项目都有一个独特的API URL。您的 API 在 API 网关后面是安全的，每次请求都需要一个 API 密钥。

  1. 转到仪表板中的设置页面。
  2. 单击侧栏中的 API。
  3. 在这个页面上找到你的APIURL、anon和service_role键。

REST API和GraphQL API都可以通过这个URL访问:

  • REST: https://<project_ref>.supabase.co/rest/v1
  • GraphQL: https://<project_ref>.supabase.co/graphql/v1

这两重路由都需要通过apikey标头来传递anon密钥。

API密钥

您将获得两个密钥：

  • 一个anon 密钥, 在浏览器环境下使用是安全的。

  • 一个service_role密钥，只能在服务器上使用。这个密钥可以绕过行级安全。千万不要在浏览器中使用这个密钥。

访问仪表板中的文档

REST API

MemFire Cloud在Dashboard中生成文档，当你对数据库进行修改时，该文档会更新。 让我们查看在数据库中创建的countries表的文档。

  1. 转到仪表板中的API页面。
  2. 在侧边栏的表和视图下找到 countries表。
  3. 使用标签在JavaScript和cURL文档之间切换。

GraphQL

我们提供的GraphQL端点（https://<project_ref>.supabase.co/graphql/v1）与任何能够传递apikey头的GraphiQL实现兼容。

一些建议的应用:

使用API

REST API

你可以直接通过HTTP请求与你的API交互，或者可以使用我们提供的客户端库。

让我们看看如何向在第一步创建的todos表提出请求。 使用提供的API URL（SUPABASE_URL）和Key（SUPABASE_ANON_KEY）。

  // 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('*')
  
  # 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>"

JS 参考: select(), insert(), update(), upsert(), delete(), rpc() (调用Postgres函数)).

GraphQL API

你可以在任何GraphQL客户端调用Supabase GraphQL API。对于我们的GraphQL例子，我们将使用urql。

  import { createClient, useQuery } from 'urql'

// Prepare API key and Authorization header
const headers = {
  apikey: <SUPABASE_ANON_KEY>,
  authorization: `Bearer ${<SUPABASE_ANON_KEY}`>
}

// Create GraphQL client
// See: https://formidable.com/open-source/urql/docs/basics/react-preact/#setting-up-the-client
const client = createClient({
  url: '<SUPABASE_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
  
  # Append /graphql/v1/ to your URL, and then use the table name as the route
curl --request POST '<SUPABASE_URL>/graphql/v1' \
-H 'apikey: <SUPABASE_ANON_KEY>' \
-H 'Authorization: Bearer <SUPABASE_ANON_KEY>' \
-d '{ "query":"{ todos(first: 3) { edges { node { id } } } }" }'

实时API

默认情况下，Realtime在你的数据库中是禁用的。让我们为todos表打开Realtime。

  1. 进入仪表板中的数据库页面。
  2. 点击侧边栏中的复制。
  3. 通过切换插入、更新和删除来控制哪些数据库事件被发送。
  4. 通过选择Source和切换每个表来控制哪些表被发送变化。
  alter publication supabase_realtime add table todos;

从客户端，我们可以监听插入`todos’表的任何新数据：

  // 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()

使用subscribe()来监听数据库变化。 实时API通过PostgreSQL的复制功能工作。Postgres将数据库变化发送到一个叫做supabase_realtime的发布，通过管理这个发布，你可以控制哪些数据被广播。

API安全

保护你的路由安全

你的API被设计成与Postgres行级安全（RLS）一起工作。如果你使用Supabase Auth，你可以根据登录的用户来限制数据。 为了控制对数据的访问，你可以使用Policy。 当你在Postgres中创建一个表时，默认情况下，行级安全是被禁用的。要启用RLS：

  1. 进入仪表板中的认证页面。
  2. 单击侧边栏中的政策。
  3. 选择启用RLS来启用行级安全。
  alter table todos enable row level security;

service_role密钥

不要在浏览器或用户可以看到的任何地方暴露 service_role 密钥。这个密钥是为了绕过行级安全而设计的 - 所以它只应该在私人服务器上使用。

service_role密钥的一个常见用例是在后端运行数据分析工作。为了支持用户ID的连接，授予服务角色对auth.users表的读取权限通常是有用的。

  grant select on table auth.users to service_role;

我们已经与GitHub合作，扫描推送到公共存储库的Supabase service_role密钥。 如果他们检测到任何具有service_role权限的密钥被推送到GitHub，他们将把API密钥转发给我们，这样我们就可以自动撤销检测到的秘密并通知你，保护你的数据免受恶意行为的影响。

对意外删除和更新的保障措施

对于所有项目，默认情况下，Postgres扩展safeupdate对所有来自API的查询都是启用的。 这可以确保任何 delete()或 update()在没有附带过滤器的情况下会失败。 为了确认通过你的项目的API进行的查询是否启用了safeupdate，可以运行以下查询：

  select usename,useconfig from pg_shadow where usename = 'authenticator' ;

useconfig的预期值应该是：

  ['session_preload_libraries=supautils, safeupdate']