API PostgREST
API REST gerada automaticamente a partir do seu schema PostgreSQL. Nenhum código de backend necessário.
Ativando o PostgREST
O PostgREST é ativado por servidor de banco de dados PostgreSQL. Para ativá-lo:
- Acesse Servidores de banco de dados no painel do sh0.
- Selecione um servidor PostgreSQL existente (ou crie um).
- Clique em Ativar PostgREST nas configurações do servidor.
- O sh0 implanta uma instância do PostgREST, conecta-a ao seu banco de dados e provisiona um domínio SSL.
Configuração
Depois de ativar o PostgREST, você pode configurar as seguintes opções no painel:
Papel anônimo
O anon_role é o papel do PostgreSQL usado para requisições não autenticadas. Por padrão, o sh0 cria um papel chamado anon com acesso somente leitura ao schema public.
Use as instruções GRANT e REVOKE do PostgreSQL para controlar o que usuários não autenticados podem acessar.
Schemas expostos
Por padrão, o PostgREST expõe apenas o schema public. Você pode configurar schemas adicionais a expor nas configurações do painel. Tabelas em schemas não expostos nunca ficam acessíveis pela API.
pg_catalog ou information_schema. Exponha apenas schemas que contenham tabelas que você quer tornar acessíveis pela API.Sintaxe de consultas
O PostgREST usa parâmetros de consulta para filtrar, ordenar, paginar e moldar a resposta. Todos os endpoints seguem o padrão:
GET https://<your-domain>/<table_name>?select=<columns>&<filters>
Filtragem
Use filtros por coluna com operadores:
| Operador | Significado | Exemplo |
|---|---|---|
| eq | Igual | ?status=eq.active |
| neq | Diferente | ?role=neq.admin |
| gt / gte | Maior que / ou igual | ?age=gte.18 |
| lt / lte | Menor que / ou igual | ?price=lt.100 |
| like / ilike | Correspondência de padrão (diferencia / não diferencia maiúsculas) | ?name=ilike.*john* |
| in | Na lista | ?id=in.(1,2,3) |
| is | IS (null, true, false) | ?deleted_at=is.null |
Paginação
Use o cabeçalho Range ou os parâmetros de consulta limit e offset:
GET /users?limit=20&offset=40&order=created_at.desc
Incorporação de recursos (joins)
O PostgREST detecta automaticamente relacionamentos de chave estrangeira e permite incorporar recursos relacionados:
GET /orders?select=id,total,customer(name,email)
Isso retorna cada pedido com o nome e o e-mail do cliente relacionado incorporados na resposta.
Autenticação com JWT
O PostgREST verifica tokens JWT enviados no cabeçalho Authorization. Quando um JWT válido é fornecido, o PostgREST muda para o papel especificado na claim role do token e define todas as claims como variáveis de sessão do PostgreSQL.
Isso se integra às políticas de segurança em nível de linha (Row-Level Security, RLS) do PostgreSQL. Por exemplo, uma política que verifica current_setting('request.jwt.claims')::json->>'sub' pode restringir linhas com base no usuário autenticado.
Especificação OpenAPI
Cada instância do PostgREST expõe uma especificação OpenAPI 3.0 ao vivo na sua URL raiz (GET /). Use-a para:
- Importar no Postman ou no Insomnia para testes.
- Gerar SDKs de cliente tipados com o openapi-generator.
- Alimentar ferramentas de documentação como o Swagger UI.