メインコンテンツまでスキップ

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というテーブル(いくつかユーザーのパブリックな情報を保存します)を作成しましょう。 これにより、GETPOSTPATCHDELETEのリクエストを受け付けることができる、todosに対応したルートが作成されます。

1. 「Table Editor」セクションに移動します。
2. 「New Table」をクリックします。
3. 「todos」というテーブル名を入力します。
4. 「Save」をクリックします。
5. 「New Column」をクリックします。
6. 「task」というカラム名を入力し、タイプを「text」にします。
7. 「Sava」をクリックします。

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テーブルのドキュメントを見てみましょう。

1. 「API」セクションに移動します。
2. 「Tables and Views」セクションで「todos」を探します。
3. タブを使用して、JavaScriptとcURLのドキュメントを切り替えます。

GraphQL

GraphQLエンドポイント(https://<project_ref>.supabase.com/graphql/v1)は、apikeyヘッダーを渡せるGraphiQL実装と互換性があります。 いくつかの推奨アプリケーションを次に紹介します。

APIの利用

REST API

HTTPリクエストを介してAPIを直接操作できますし、当社が提供するクライアント・ライブラリーを使用できます。

それでは、最初のステップで作成したtodosテーブルに、取得したAPI URL([SUPABASE_URL])とキー([SUPABASE_ANON_KEY])を使ってリクエストする方法を見てみましょう。

// JSクライアントを初期化
import { createClient } from '@supabase/supabase-js'
const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)

// リクエストを作成
let { data: todos, error } = await supabase
.from('todos')
.select('*')

GraphQL API

note

SQLスキーマからGraphQLスキーマを再構築するには、select graphql.rebuild_schema();を呼び出します。 SQLスキーマを変更した後は、必ずGraphQLスキーマを再構築するようにしてください。

Supabase GraphQL APIでは、任意のGraphQLクライアントを使用できます。今回のGraphQLの例では、urlqlを使用することにします。

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

リアルタイムの管理

デフォルトでは、データベースのリアルタイムは無効になっています。それでは、todosテーブルのリアルタイムを有効にしてみましょう。

1. 「Database」セクションに移動します。
2. サイドバーの「Replication」をクリックします。
3. Insert/Update/Deleteのトグルを切り替えることで、どのデータベース・イベントを送信するか制御します。
4. 「Source」をクリックしてテーブルを切り替えることで、どのテーブルの変更を反映するか制御できます。

これで、todoテーブルに挿入される新しいデータをリッスンできるようになりました。

// 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を有効にすることでセキュリティーを確保してください。

1. 「Authentication」セクションに移動します。
2. サイドバーの「Policies」をクリックします。
3. 「Enable RLS」をクリックして、行単位セキュリティーを有効にします。

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"]