Creating API Routes

API routes are automatically created when you create Postgres Tables, Views, or Functions.

Create a table#

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.

Go to the Table editor page in the Dashboard.
Click New Table and create a table with the name todos.
Click Save.
Click New Column and create a column with the name task and type text.
Click Save.

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.

Go to the Settings page in the Dashboard.
Click API in the sidebar.
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://<project_ref>.supabase.co/rest/v1
GraphQL: https://<project_ref>.supabase.co/graphql/v1

Both of these routes require the anon key to be passed through an apikey header.

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:

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

JS Reference: select(), insert(), update(), upsert(), delete(), 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.

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

Realtime API#

By default Realtime is disabled on your database. Let's turn on Realtime for the todos table.

Go to the Database page in the Dashboard.
Click on Replication in the sidebar.
Control which database events are sent by toggling Insert, Update, and Delete.
Control which tables broadcast changes by selecting Source and toggling each table.

From the client, we can listen to any new data that is inserted into the todos table:

// 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() to listen to database changes. The Realtime API works through PostgreSQL's replication functionality. Postgres sends database changes to a publication called supabase_realtime, and by managing this publication you can control which data is broadcast.

Edit this page on GitHub