API
概要
Supabaseはデータベースのスキーマから直接3つのタイプのAPIを生成します。
- REST - レストフルなインターフェースでやりとり
- Realtime - データベースの更新をリッスン
- GraphQL - ベータ版
これらのAPIは次の特徴があります。
- 即時性と自動生成
データベースを更新すると、その変更内容がAPIを通じてすぐアクセス可能になります。 - ドキュメントの生成
Supabaseは、データベースを変更した際、ダッシュボードに更新されたドキュメントを生成します。 - セキュア
APIはPostgreSQLの行単位セキュリティーと連動するように設定されており、APIゲートウェイの背後でキーによる認証が有効になっています。 - 高速
基本的な読み込みのベンチマークでは、Firebaseと比較して300%以上の高速化を実現しています。APIはPostgres上の非常に薄い層であり、Postgresがほとんどの力仕事をします。 - スケーラブル
APIは数千の同時リクエストに対応しており、サーバレスの処理にも適しています。
REST API
Supabaseは、PostgRESTを用いたRESTfulなAPIを提供しています。これは、Postgresの上の非常に薄いAPI層です。 これは、CRUDのAPIに必要なすべてを提供します。
- 基本的なCRUD操作
- 深くネストされた結合により、1回のフェッチで複数のテーブルからデータを取得可能
- Potgresのビューと連動
- Postgresの関数と連動
- 行単位セキュリティー、ロール、およびGRANTなどの、Postgresのセキュリティモデルと連動
GraphQL API
note
GraphQLはベータ版であり、変更される可能性があります。2022年3月28日以降に作成されたセルフ・ホストでのセットアップとSupabaseプロジェクトでのみ利用可能です。
SupabaseのGraphQLは、GraphQLのためのオープンソースのPostgreSQL拡張であるpg_graphqlを通じて機能します。
リアルタイムAPI
SupabaseはRealtimeを使って、リアルタイムAPIを提供しています。これを利用して、データベースの変更をWebSocketで待ち受けることができます。 RealtimeはPostgreSQLに組み込まれた論理的なレプリケーションを利用しています。Postgresのパブリケーションを管理するだけで、リアルタイムAPIを管できますす。
はじめに
すべてのAPIは、データベースのテーブルから自動作成されます。データベースにテーブルや関数を追加した後、提供されるAPIを使用できます。
APIルートの作成
APIルートは、Postgresのテーブル、ビュー、または関数を作成する際、自動的に作成されます。
最初のAPIルートを作成するために、todos
というテーブル(いくつかユーザーのパブリックな情報を保存します)を作成しましょう。
これにより、GET
、POST
、PATCH
、DELETE
のリクエストを受け付けることができる、todos
に対応したルートが作成されます。
- UI
- SQL
1. 「Table Editor」セクションに移動します。
2. 「New Table」をクリックします。
3. 「todos」というテーブル名を入力します。
4. 「Save」をクリックします。
5. 「New Column」をクリックします。
6. 「task」というカラム名を入力し、タイプを「text」にします。
7. 「Sava」をクリックします。
-- タスクを格納する列を持つ「todos」というテーブルを作成します。
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. 「Settings」セクションに移動します。
2. サイドバーの「API」をクリックします。
3. そのページ内で、API URLを探します。
4. そのページ内で、「anon」と「service_role」キーを探します。
REST APIとGraphQL APIは、どちらも次のURLよりアクセスできます。
- REST:
https://<project_ref>.supabase.co/rest/v1
- GraphQL:
https://<project_ref>.supabase.co/graphql/v1
これらのルートはどちらもanon
キーがapikey
ヘッダーを通して渡されることを必要があります。
APIキー
キーは、ダッシュボード内の、上記URLと同じ場所にあります。
鍵は2つ用意されています。
anon
キーはブラウザのコンテキストで使用しても安全です。service_role
キーはサーバー上でのみ使用します。このキーは行単位セキュリティーを回避できます。
ドキュメントへのアクセス
REST API
Supabaseは、データベースの変更に応じてドキュメントを更新して、ダッシュボードに生成します。
最初のステップで作成したtodos
テーブルのドキュメントを見てみましょう。
- UI
1. 「API」セクションに移動します。
2. 「Tables and Views」セクションで「todos」を探します。
3. タブを使用して、JavaScriptとcURLのドキュメントを切り替えます。
GraphQL
GraphQLエンドポイント(https://<project_ref>.supabase.com/graphql/v1
)は、apikey
ヘッダーを渡せるGraphiQL実装と互換性があります。
いくつかの推奨アプリケーションを次に紹介します。
- paw.cloud
- insomnia.rest
- postman.com/graphql
- セルフホスティングのGraphiQL:GraphiQLはシンプルなHTMLファイルを通して提供できます。詳しくはこちらのDiscussionを参照
APIの利用
REST API
HTTPリクエストを介してAPIを直接操作できますし、当社が提供するクライアント・ライブラリーを使用できます。
それでは、最初のステップで作成したtodos
テーブルに、取得したAPI URL([SUPABASE_URL]
)とキー([SUPABASE_ANON_KEY]
)を使ってリクエストする方法を見てみましょう。
- JavaScript
- cURL
// JSクライアントを初期化
import { createClient } from '@supabase/supabase-js'
const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)
// リクエストを作成
let { data: todos, error } = await supabase
.from('todos')
.select('*')
# URLに/rest/v1/を追加して、テーブル名をルートとして使用
curl '[SUPABASE_URL]/rest/v1/todos' \
-H "apikey: [SUPABASE_ANON_KEY]" \
-H "Authorization: Bearer SUPABASE_ANON_KEY"
GraphQL API
note
SQLスキーマからGraphQLスキーマを再構築するには、select graphql.rebuild_schema();
を呼び出します。
SQLスキーマを変更した後は、必ずGraphQLスキーマを再構築するようにしてください。
Supabase GraphQL APIでは、任意のGraphQLクライアントを使用できます。今回のGraphQLの例では、urlqlを使用することにします。
- Javascript
- cURL
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 } } } }" }'
リアルタイムの管理
デフォルトでは、データベースのリアルタイムは無効になっています。それでは、todos
テーブルのリアルタイムを有効にしてみましょう。
- UI
- SQL
1. 「Database」セクションに移動します。
2. サイドバーの「Replication」をクリックします。
3. Insert/Update/Deleteのトグルを切り替えることで、どのデータベース・イベントを送信するか制御します。
4. 「Source」をクリックしてテーブルを切り替えることで、どのテーブルの変更を反映するか制御できます。
alter publication supabase_realtime add table todos;
これで、todo
テーブルに挿入される新しいデータをリッスンできるようになりました。
- 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()
データベースの変更をリッスンするには、subscribe()を使用します。
リアルタイムAPIは、PostgreSQLのレプリケーション機能を介して動作します。Postgresはデータベースの変更を、supabase_realtime
と呼ばれる「パブリケーション」に送信します。
APIのセキュリティー
ルートのセキュア化
APIは、Postgresの行単位セキュリティーと連動するように設計されています。Supabase Authを使用すれば、ログインしたユーザーに基づいてデータを制限できます。 データへのアクセスを制御するには、ポリシーを使用します。 Postgresでテーブルを作成すると、デフォルトでは行単位セキュリティー(RLS)が無効になっています。RLSを有効にすることでセキュリティーを確保してください。
- UI
- SQL
1. 「Authentication」セクションに移動します。
2. サイドバーの「Policies」をクリックします。
3. 「Enable RLS」をクリックして、行単位セキュリティーを有効にします。
alter table todos enable row level security;
service_role
キー
ブラウザーやユーザーが見ることのできる場所にservice_role
キーを決して公開しないでください。このキーは行単位セキュリティーをバイパスするように設計されています。したがって、公開されていないサーバーでのみ使用するようにしてください。
GitHubと提携し、Supabaseのservice_role
キーが公開リポジトリーにプッシュされていないかスキャンします。
GitHubがservice_role権限のあるキーを検出すると、そのキーをSupbaseに転送します。Supabaseは自動的にそのキーを失効してお知らせします。それにより、データを悪質業者から保護します。
誤って削除や更新をしてしまわないための保護機能
新しいプロジェクトでは、デフォルトで、APIから来るすべてのクエリに対してPostgres拡張機能のsafeupdateが有効になっています。
これにより、付随するフィルターが提供されていない場合に、delete()
またはupdate()
が失敗することを保証します。
これを無効にするには、ダッシュボードのSQLエディターで以下のクエリを実行します。
select usename,useconfig from pg_shadow where usename = 'authenticator' ;
useconfig` に期待される値は次のとおりです。
["session_preload_libraries=supautils, safeupdate"]