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

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

SQL

-- タスクを格納する列を持つ「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

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

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

cURL

# URLに/rest/v1/を追加して、テーブル名をルートとして使用
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

note

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

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

Javascript

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

cURL

# 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

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

SQL

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

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

SQL

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