Como Usar a API do Supabase: Um Guia Completo

O Supabase emergiu rapidamente como uma poderosa alternativa open-source ao Firebase, fornecendo aos desenvolvedores um conjunto de ferramentas construídas em torno de um banco de dados PostgreSQL. Em seu núcleo, o Supabase oferece uma camada de API em tempo real instantânea em cima do seu banco de dados, acelerando significativamente o desenvolvimento backend. Este guia fornece uma visão abrangente de como aproveitar a API do Supabase, abordando tudo, desde a configuração inicial e operações básicas até segurança, personalização e segurança de tipo.

1. Introdução: O que é a API do Supabase?

Ao contrário do desenvolvimento backend tradicional, onde você pode passar um tempo considerável construindo endpoints REST ou GraphQL para interagir com seu banco de dados, o Supabase gera automaticamente uma API segura e performática para você. Quando você cria uma tabela em seu banco de dados PostgreSQL do Supabase, o Supabase utiliza PostgREST, uma ferramenta open-source, para introspectar seu esquema de banco de dados e fornecer endpoints RESTful correspondentes.

Principais Benefícios:

• Backend Instantâneo: Obtenha endpoints de API funcionais assim que você definir seu esquema de banco de dados.
• Capacidades em Tempo Real: Assine mudanças no banco de dados via WebSockets.
• Baseado em PostgreSQL: Aproveite o poder, flexibilidade e maturidade do PostgreSQL, incluindo recursos como Segurança a Nível de Linha (RLS).
• Múltiplos Métodos de Interação: Interaja via REST, GraphQL (suportado pela comunidade), ou bibliotecas cliente do Supabase (JavaScript, Python, Dart, etc.).
• Extensibilidade: Crie funções serverless personalizadas (Funções de Edge) para lógica ou integrações complexas.

Este guia foca principalmente na API REST e sua interação via bibliotecas cliente, bem como nas Funções Edge do Supabase.

2. Começando com a API do Supabase

A forma mais fácil de entender a API do Supabase é mergulhar de cabeça. Vamos supor que você tenha um projeto do Supabase configurado (caso contrário, visite supabase.com e crie um gratuitamente) e tenha criado uma tabela simples, por exemplo, profiles:

-- Criar uma tabela para perfis públicos
create table profiles (
  id uuid references auth.users not null primary key,
  updated_at timestamp with time zone,
  username text unique,
  avatar_url text,
  website text,

  constraint username_length check (char_length(username) >= 3)
);

-- Configurar Segurança a Nível de Linha (RLS)
-- Veja https://supabase.com/docs/guides/auth/row-level-security para mais detalhes.
alter table profiles
  enable row level security;

create policy "Perfis públicos podem ser visualizados por todos." on profiles
  for select using (true);

create policy "Usuários podem inserir seu próprio perfil." on profiles
  for insert with check (auth.uid() = id);

create policy "Usuários podem atualizar seu próprio perfil." on profiles
  for update using (auth.uid() = id);

-- Este trigger cria automaticamente uma entrada de perfil quando um novo usuário se registra via Supabase Auth.
-- Veja https://supabase.com/docs/guides/auth/managing-user-data#using-triggers para mais detalhes.
create function public.handle_new_user()
returns trigger as $$
begin
  insert into public.profiles (id, username)
  values (new.id, new.raw_user_meta_data->>'username');
  return new;
end;
$$ language plpgsql security definer;
create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

(Nota: O exemplo acima utiliza profiles, alinhando-se com os exemplos padrão do Supabase. O conceito se aplica igualmente à uma tabela todos ou qualquer outra tabela que você criar.)

Encontrando suas Credenciais de API:

Todo projeto do Supabase vem com credenciais de API únicas:

1. URL do Projeto: Seu endpoint único do Supabase (ex: https://<your-project-ref>.supabase.co).
2. Chaves de API: Encontradas no painel do seu Projeto Supabase sob Configurações do Projeto > API.

• anon (chave pública): Esta chave é segura para uso em aplicações do lado do cliente (como navegadores ou aplicativos móveis). Depende da Segurança a Nível de Linha (RLS) para controlar o acesso aos dados.
• service_role (chave de serviço): Esta é uma chave secreta com privilégios administrativos totais, ignorando o RLS. Nunca exponha esta chave em código do lado do cliente. Use-a apenas em ambientes de servidor seguros (como servidores backend ou funções serverless).

Interagindo com a API (usando a Biblioteca de Cliente Supabase JS):

O Supabase fornece bibliotecas cliente para simplificar as interações com a API. Veja como você usaria a biblioteca JavaScript (supabase-js):

// 1. Importar e inicializar o cliente
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = 'https://<your-project-ref>.supabase.co'
const supabaseAnonKey = '<your-anon-key>'

const supabase = createClient(supabaseUrl, supabaseAnonKey)

// 2. Buscar dados (SELECT *)
async function getProfiles() {
  const { data, error } = await supabase
    .from('profiles')
    .select('*')

  if (error) console.error('Erro ao buscar perfis:', error)
  else console.log('Perfis:', data)
}

// 3. Inserir dados (INSERT)
async function createProfile(userId, username) {
  const { data, error } = await supabase
    .from('profiles')
    .insert([
      { id: userId, username: username, updated_at: new Date() },
    ])
    .select() // Retorna os dados inseridos

  if (error) console.error('Erro ao criar perfil:', error)
  else console.log('Perfil criado:', data)
}

// 4. Atualizar dados (UPDATE)
async function updateProfileUsername(userId, newUsername) {
  const { data, error } = await supabase
    .from('profiles')
    .update({ username: newUsername, updated_at: new Date() })
    .eq('id', userId) // Atualiza apenas onde o id corresponde
    .select()

  if (error) console.error('Erro ao atualizar perfil:', error)
  else console.log('Perfil atualizado:', data)
}

// 5. Deletar dados (DELETE)
async function deleteProfile(userId) {
  const { data, error } = await supabase
    .from('profiles')
    .delete()
    .eq('id', userId) // Deleta apenas onde o id corresponde

  if (error) console.error('Erro ao deletar perfil:', error)
  // Nota: Deletar frequentemente retorna dados mínimos em caso de sucesso a menos que .select() seja utilizado *antes* de .delete() em algumas versões/configurações.
  else console.log('Perfil deletado com sucesso')
}

// Exemplo de Uso (supondo que você tenha um ID de usuário)
// getProfiles();
// createProfile('some-uuid-v4', 'new_user');
// updateProfileUsername('some-uuid-v4', 'updated_username');
// deleteProfile('some-uuid-v4');

Este quickstart demonstra as operações CRUD fundamentais (Criar, Ler, Atualizar, Deletar) usando a biblioteca cliente, que internamente chama a API REST.

3. A API REST Auto-Gerada do Supabase

Embora as bibliotecas cliente sejam convenientes, entender a API REST subjacente gerada pelo PostgREST é crucial.

Estrutura de Endpoint da API:

O URL base para a API REST é tipicamente: https://<your-project-ref>.supabase.co/rest/v1/

Endpoints são criados automaticamente para suas tabelas:

• GET /rest/v1/your_table_name: Recupera linhas da tabela.
• POST /rest/v1/your_table_name: Insere novas linhas na tabela.
• PATCH /rest/v1/your_table_name: Atualiza linhas existentes na tabela.
• DELETE /rest/v1/your_table_name: Deleta linhas da tabela.

Autenticação:

As requisições de API devem incluir sua chave de API no cabeçalho apikey e geralmente um cabeçalho Authorization contendo Bearer <your-api-key> (frequentemente a mesma chave anon para requisições do lado do cliente, ou a chave service_role para o lado do servidor).

apikey: <your-anon-or-service-role-key>
Authorization: Bearer <your-anon-or-service-role-key>

Operações Comuns (usando exemplos curl):

Vamos replicar os exemplos anteriores usando curl contra a API REST diretamente. Substitua os espaços reservados conforme necessário.

Buscar Dados (GET):

curl 'https://<ref>.supabase.co/rest/v1/profiles?select=*' \
  -H "apikey: <anon-key>" \
  -H "Authorization: Bearer <anon-key>"

Inserir Dados (POST):

curl 'https://<ref>.supabase.co/rest/v1/profiles' \
  -X POST \
  -H "apikey: <anon-key>" \
  -H "Authorization: Bearer <anon-key>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \# Opcional: Retorna a(s) linha(s) inserida(s) \
  -d '{ "id": "some-uuid", "username": "rest_user" }'

Atualizar Dados (PATCH): (Atualizar perfil onde o username é 'rest_user')

curl 'https://<ref>.supabase.co/rest/v1/profiles?username=eq.rest_user' \
  -X PATCH \
  -H "apikey: <anon-key>" \
  -H "Authorization: Bearer <anon-key>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{ "website": "https://example.com" }'

Deletar Dados (DELETE): (Deletar perfil onde o username é 'rest_user')

curl 'https://<ref>.supabase.co/rest/v1/profiles?username=eq.rest_user' \
  -X DELETE \
  -H "apikey: <anon-key>" \
  -H "Authorization: Bearer <anon-key>"

Filtragem, Seleção, Ordenação, Paginação:

A API REST suporta poderosas consultas via parâmetros de URL:

• Selecionando Colunas: ?select=column1,column2
• Filtragem (Igualdade): ?column_name=eq.value (ex: ?id=eq.some-uuid)
• Filtragem (Outros Operadores): gt (maior que), lt (menor que), gte, lte, neq (não igual), like, ilike (como insensitive), in (ex: ?status=in.(active,pending))
• Ordenação: ?order=column_name.asc ou ?order=column_name.desc (adicionar .nullsfirst ou .nullslast se necessário)
• Paginação: ?limit=10&offset=0 (buscar os primeiros 10), ?limit=10&offset=10 (buscar os próximos 10)

Documentação de API Auto-Gerada:

Um dos recursos mais úteis do Supabase é a documentação de API auto-gerada disponível diretamente dentro do painel do seu projeto.

1. Navegue até o seu projeto Supabase.
2. Clique no ícone da Documentação da API (normalmente parece <>) na barra lateral esquerda.
3. Selecione uma tabela em "Tabelas e Visualizações".
4. Você verá documentação detalhada para os endpoints REST específicos daquela tabela, incluindo:

• Exemplos de requisições (Bash/curl, JavaScript).
• Filtros, seletores e modificadores disponíveis.
• Descrições de colunas e tipos de dados.

Essa documentação interativa é inestimável para entender como estruturar suas chamadas de API.

4. Gerando Tipos para Desenvolvimento Aprimorado Usando a API do Supabase

Para projetos que usam TypeScript ou outras linguagens tipadas, o Supabase fornece uma forma de gerar definições de tipo diretamente do seu esquema de banco de dados. Isso traz benefícios significativos:

• Segurança de Tipo: Captura erros em tempo de compilação em vez de tempo de execução.
• Autocompletar: Receba sugestões inteligentes em seu editor de código para nomes de tabelas, nomes de colunas e parâmetros de função.
• Manutenção Aprimorada: Tipos servem como documentação viva para suas estruturas de dados.

Gerando Tipos usando o Supabase CLI:

1. Instalar o Supabase CLI: Siga as instruções em https://supabase.com/docs/guides/cli.
2. Fazer login: supabase login
3. Vincular seu projeto: supabase link --project-ref <your-project-ref> (Execute isso no diretório do seu projeto local). Você pode precisar fornecer uma senha de banco de dados.
4. Gerar tipos:

supabase gen types typescript --linked > src/database.types.ts
# Ou especifique project-id se não estiver vinculado ou em um contexto diferente
# supabase gen types typescript --project-id <your-project-ref> > src/database.types.ts

Este comando inspeciona o esquema do banco de dados do seu projeto Supabase vinculado e gera um arquivo TypeScript (database.types.ts neste exemplo) contendo interfaces para suas tabelas, visualizações e tipos de argumentos/retornos de função.

Usando Tipos Gerados:

Você pode então importar esses tipos em seu código de aplicação:

import { createClient } from '@supabase/supabase-js'
// Importar os tipos gerados
import { Database } from './database.types' // Ajustar o caminho conforme necessário

const supabaseUrl = 'https://<your-project-ref>.supabase.co'
const supabaseAnonKey = '<your-anon-key>'

// Fornecer o tipo de Database para createClient
const supabase = createClient<Database>(supabaseUrl, supabaseAnonKey)

// Agora você obtém segurança de tipo e autocompletar!
async function getSpecificUserProfile(username: string) {
  // Autocompleta nomes de tabela ('profiles')
  const { data, error } = await supabase
    .from('profiles')
    // Autocompleta nomes de coluna ('id', 'username', 'website')
    .select('id, username, website')
    // Verifica se o valor corresponde ao tipo da coluna
    .eq('username', username)
    .single() // Espera um único resultado ou nulo

  if (error) {
    console.error('Erro ao buscar perfil:', error)
    return null;
  }

  // 'data' agora está corretamente tipado com base na sua consulta de seleção
  if (data) {
    console.log(`ID do Usuário: ${data.id}, Website: ${data.website}`);
    // console.log(data.non_existent_column); // <-- Erro TypeScript!
  }

  return data;
}

Gerar tipos é uma prática altamente recomendada para um desenvolvimento robusto de aplicações com Supabase.

5. Criando Rotas de API Personalizadas do Supabase com Funções Edge

Enquanto a API REST auto-gerada cobre operações CRUD padrão, você frequentemente precisará de lógica personalizada no lado do servidor para:

• Integrar com serviços de terceiros (ex: Stripe, Twilio).
• Executar cálculos complexos ou agregações de dados.
• Executar lógica que requer privilégios elevados (service_role) sem expor a chave ao cliente.
• Impor regras de negócios complexas.

As Funções Edge do Supabase fornecem uma maneira de implantar funções TypeScript baseadas em Deno globalmente na borda, perto dos seus usuários.

Criando uma Função Edge:

1. Inicializar Funções (se ainda não foi feito): supabase functions new hello-world (execute no diretório do seu projeto vinculado). Isso cria um arquivo supabase/functions/hello-world/index.ts.

Escreva o código da sua função:

// supabase/functions/hello-world/index.ts
import { serve } from 'https://deno.land/std@0.177.0/http/server.ts' // Use a versão apropriada do std

serve(async (req) => {
  // Você pode acessar cabeçalhos da requisição, método, corpo etc. a partir de 'req'
  console.log(`Requisição recebida para: ${req.url}`);

  // Exemplo: Acessando DB do Supabase dentro da função
  // Nota: Requer configurar o cliente Supabase *dentro* da função
  // Use variáveis de ambiente para segredos!
  // import { createClient } from '@supabase/supabase-js'
  // const supabaseAdmin = createClient(
  //   Deno.env.get('SUPABASE_URL') ?? '',
  //   Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
  // )
  // const { data: users, error } = await supabaseAdmin.from('profiles').select('*').limit(10);

  const data = {
    message: `Olá da Edge!`,
    // users: users // Exemplo se buscar dados
  }

  return new Response(
    JSON.stringify(data),
    { headers: { 'Content-Type': 'application/json' } },
  )
})

Implante a função:

supabase functions deploy hello-world --no-verify-jwt
# Use --no-verify-jwt para funções acessíveis publicamente
# Omitir ou definir --verify-jwt=true para exigir um JWT de autenticação do Supabase válido

Chame a função:
Você pode chamar funções implantadas via requisições HTTP POST (ou GET, dependendo da lógica da função) para seu endpoint único:
https://<your-project-ref>.supabase.co/functions/v1/hello-world

Usando curl:

curl -X POST 'https://<ref>.supabase.co/functions/v1/hello-world' \
  -H "Authorization: Bearer <user-jwt-if-required>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Functions"}' # Corpo de requisição opcional

Ou usando o cliente JavaScript do Supabase:

const { data, error } = await supabase.functions.invoke('hello-world', {
  method: 'POST', // ou 'GET', etc.
  body: { name: 'Functions' }
})

As Funções Edge são uma ferramenta poderosa para estender as capacidades do seu backend Supabase além de operações simples de banco de dados.

6. Chaves de API e Protegendo Sua API Supabase

Entender as chaves de API e implementar medidas de segurança adequadas é inegociável.

Recapitulando Chaves de API:

• anon (chave pública): Para uso do lado do cliente. Depende totalmente da Segurança a Nível de Linha (RLS) para proteção de dados.
• service_role (chave de serviço): Para uso SOMENTE do lado do servidor. Ignora o RLS, concedendo acesso total ao banco de dados. Proteja esta chave cuidadosamente.

O Papel Crucial da Segurança a Nível de Linha (RLS):

RLS é a pedra angular da segurança do Supabase ao usar a chave anon. Ele permite que você defina políticas de controle de acesso detalhadas diretamente no banco de dados PostgreSQL. As políticas são essencialmente regras SQL que determinam quais linhas um usuário pode visualizar, inserir, atualizar ou deletar com base em seu status autenticado, ID de usuário, papel ou outros critérios.

Habilitando RLS:

Por padrão, o RLS é desativado em novas tabelas. Você deve habilitá-lo para qualquer tabela que você pretenda acessar do lado do cliente usando a chave anon.

-- Habilitar RLS na tabela 'profiles'
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

-- IMPORTANTE: Se nenhuma política for definida após habilitar RLS,
-- o acesso é implicitamente negado para todas as operações (exceto para o proprietário da tabela).

Criando Políticas RLS:

Políticas definem a cláusula USING (para acesso de leitura como SELECT, UPDATE, DELETE) e a cláusula WITH CHECK (para acesso de gravação como INSERT, UPDATE).

Exemplo 1: Permitir que usuários logados leiam todos os perfis:

CREATE POLICY "Permitir acesso de leitura autenticado"
ON profiles FOR SELECT
USING ( auth.role() = 'authenticated' );

Exemplo 2: Permitir que usuários visualizem apenas seu próprio perfil:

CREATE POLICY "Permitir acesso de leitura individual"
ON profiles FOR SELECT
USING ( auth.uid() = id ); -- Assume que a coluna 'id' corresponde ao UUID do usuário do Supabase Auth

Exemplo 3: Permitir que usuários atualizem apenas seu próprio perfil:

CREATE POLICY "Permitir acesso de atualização individual"
ON profiles FOR UPDATE
USING ( auth.uid() = id ) -- Especifica quais linhas podem ser alvo de atualização
WITH CHECK ( auth.uid() = id ); -- Garante que quaisquer *novos* dados ainda correspondam à condição

Exemplo 4: Permitir que usuários insiram seu próprio perfil:

CREATE POLICY "Permitir acesso de inserção individual"
ON profiles FOR INSERT
WITH CHECK ( auth.uid() = id );

Você pode visualizar, criar e gerenciar políticas RLS diretamente no Painel do Supabase em Autenticação > Políticas.

Princípios de Segurança Chave:

1. Sempre habilite RLS em tabelas acessadas via a chave anon.
2. Defina políticas explícitas para SELECT, INSERT, UPDATE, DELETE conforme necessário. Comece com políticas restritivas e amplie o acesso com cuidado.
3. Nunca exponha a chave service_role em código do lado do cliente ou em ambientes inseguros.
4. Use Funções Edge para operações que exigem privilégios elevados ou lógica complexa do lado do servidor, protegendo sua chave service_role dentro das variáveis de ambiente seguras da função.
5. Revise regularmente suas políticas RLS para garantir que atendam aos requisitos de segurança da sua aplicação.

7. Mapeando Conceitos SQL para a API do Supabase (SQL para API)

Se você está familiarizado com SQL, entender como operações SQL comuns se mapeiam para a API do Supabase (tanto REST quanto bibliotecas cliente) é útil.

SELECT * FROM my_table;

• REST: GET /rest/v1/my_table?select=*
• JS: supabase.from('my_table').select('*')

SELECT column1, column2 FROM my_table WHERE id = 1;

• REST: GET /rest/v1/my_table?select=column1,column2&id=eq.1
• JS: supabase.from('my_table').select('column1, column2').eq('id', 1)

INSERT INTO my_table (column1, column2) VALUES ('value1', 'value2');

• REST: POST /rest/v1/my_table com o corpo JSON {"column1": "value1", "column2": "value2"}
• JS: supabase.from('my_table').insert({ column1: 'value1', column2: 'value2' })

UPDATE my_table SET column1 = 'new_value' WHERE id = 1;

• REST: PATCH /rest/v1/my_table?id=eq.1 com o corpo JSON {"column1": "new_value"}
• JS: supabase.from('my_table').update({ column1: 'new_value' }).eq('id', 1)

DELETE FROM my_table WHERE id = 1;

• REST: DELETE /rest/v1/my_table?id=eq.1
• JS: supabase.from('my_table').delete().eq('id', 1)

Joins: Enquanto a sintaxe SQL JOIN direta não é usada nas chamadas REST básicas, você pode buscar dados relacionados usando:

• Relações de Chaves Estrangeiras: ?select=*,related_table(*) busca dados de tabelas relacionadas definidas por chaves estrangeiras.
• JS: supabase.from('my_table').select('*, related_table(*)')
• RPC (Chamadas de Procedimento Remoto): Para joins ou lógica complexa, crie uma função PostgreSQL e chame-a através da API.

-- Exemplo de função SQL
CREATE FUNCTION get_user_posts(user_id uuid)
RETURNS TABLE (post_id int, post_content text) AS $$
  SELECT posts.id, posts.content
  FROM posts
  WHERE posts.author_id = user_id;
$$ LANGUAGE sql;

• REST: POST /rest/v1/rpc/get_user_posts com o corpo JSON {"user_id": "some-uuid"}
• JS: supabase.rpc('get_user_posts', { user_id: 'some-uuid' })

8. Usando Esquemas Personalizados com a API do Supabase

Por padrão, as tabelas que você cria no Editor SQL do Supabase residem no esquema public. Para melhor organização, nomenclatura ou gerenciamento de permissões, você pode querer usar esquemas PostgreSQL personalizados.

Criando um Esquema Personalizado:

CREATE SCHEMA private_schema;

Criando Tabelas em um Esquema Personalizado:

CREATE TABLE private_schema.sensitive_data (
  id serial primary key,
  payload jsonb
);

Acessando Tabelas em Esquemas Personalizados via API:

A camada PostgREST do Supabase detecta automaticamente tabelas em esquemas que não sejam public.

• API REST: Os endpoints da API permanecem os mesmos (/rest/v1/table_name), mas o PostgREST expõe tabelas de outros esquemas por padrão. Você pode precisar gerenciar o acesso através de papéis e concessões no PostgreSQL se desejar controle de acesso a nível de esquema mais detalhado além do RLS padrão. Se houver uma colisão de nomes (mesmo nome de tabela no public e em outro esquema), você pode precisar de configuração específica ou usar RPC. Verifique a documentação do PostgREST para gerenciar a visibilidade do esquema, se necessário.
• Bibliotecas Cliente: As bibliotecas cliente funcionam sem problemas. Você simplesmente faz referência ao nome da tabela como de costume:

// Acessando uma tabela em 'private_schema' (assumindo que RLS/permissões permitam)
const { data, error } = await supabase
  .from('sensitive_data') // Não é necessário prefixar com o nome do esquema aqui
  .select('*')
  .eq('id', 1);

O Supabase cuida de mapear o nome da tabela para o esquema correto nos bastidores. Certifique-se de que suas políticas RLS façam referência corretamente às tabelas se envolverem consultas ou funções entre esquemas.

Usar esquemas personalizados é uma prática padrão do PostgreSQL que o Supabase suporta totalmente, permitindo uma organização de banco de dados mais estruturada.

9. Conclusão

A API do Supabase oferece uma maneira extraordinariamente eficiente de construir aplicações ao fornecer acesso instantâneo, seguro e escalável ao seu banco de dados PostgreSQL. Desde os endpoints REST auto-gerados e bibliotecas cliente úteis até a robustez da segurança proporcionada pela Segurança a Nível de Linha e a extensibilidade oferecida pelas Funções Edge, o Supabase capacita os desenvolvedores a se concentrarem na construção de recursos em vez de infraestrutura backend repetitiva.

Ao entender os conceitos fundamentais – chaves de API, RLS, a estrutura REST, geração de tipos e funções personalizadas – você pode aproveitar efetivamente todo o poder da plataforma Supabase. Lembre-se de priorizar a segurança.