API PostgREST
Une API REST générée automatiquement à partir de votre schéma PostgreSQL. Aucun code backend requis.
Activer PostgREST
PostgREST s'active serveur de base de données PostgreSQL par serveur. Pour l'activer :
- Ouvrez Serveurs de bases de données dans le tableau de bord sh0.
- Sélectionnez un serveur PostgreSQL existant (ou créez-en un).
- Cliquez sur Activer PostgREST dans les paramètres du serveur.
- sh0 déploie une instance PostgREST, la connecte à votre base de données et provisionne un domaine SSL.
Configuration
Une fois PostgREST activé, vous pouvez configurer les paramètres suivants depuis le tableau de bord :
Rôle anonyme
anon_role est le rôle PostgreSQL utilisé pour les requêtes non authentifiées. Par défaut, sh0 crée un rôle nommé anon avec un accès en lecture seule au schéma public.
Utilisez les instructions PostgreSQL GRANT et REVOKE pour contrôler ce à quoi les utilisateurs non authentifiés peuvent accéder.
Schémas exposés
Par défaut, PostgREST n'expose que le schéma public. Vous pouvez configurer d'autres schémas à exposer dans les paramètres du tableau de bord. Les tables des schémas non exposés ne sont jamais accessibles par l'API.
pg_catalog ou information_schema. N'exposez que les schémas contenant des tables que vous voulez rendre accessibles par l'API.Syntaxe des requêtes
PostgREST utilise les paramètres de requête pour filtrer, trier, paginer et façonner la réponse. Tous les endpoints suivent le modèle :
GET https://<your-domain>/<table_name>?select=<columns>&<filters>
Filtrage
Utilisez des filtres par colonne avec des opérateurs :
| Opérateur | Signification | Exemple |
|---|---|---|
| eq | Égal | ?status=eq.active |
| neq | Différent | ?role=neq.admin |
| gt / gte | Supérieur à / ou égal | ?age=gte.18 |
| lt / lte | Inférieur à / ou égal | ?price=lt.100 |
| like / ilike | Correspondance de motif (sensible / insensible à la casse) | ?name=ilike.*john* |
| in | Dans la liste | ?id=in.(1,2,3) |
| is | IS (null, true, false) | ?deleted_at=is.null |
Pagination
Utilisez l'en-tête Range ou les paramètres de requête limit et offset :
GET /users?limit=20&offset=40&order=created_at.desc
Imbrication de ressources (jointures)
PostgREST détecte automatiquement les relations de clé étrangère et permet d'imbriquer les ressources liées :
GET /orders?select=id,total,customer(name,email)
Cette requête renvoie chaque commande avec le nom et l'adresse e-mail du client associé imbriqués dans la réponse.
Authentification par JWT
PostgREST vérifie les jetons JWT transmis dans l'en-tête Authorization. Lorsqu'un JWT valide est fourni, PostgREST bascule sur le rôle indiqué dans la claim role du jeton et définit toutes les claims comme variables de session PostgreSQL.
Ce mécanisme s'intègre aux politiques de sécurité au niveau des lignes (Row-Level Security, RLS) de PostgreSQL. Par exemple, une politique qui vérifie current_setting('request.jwt.claims')::json->>'sub' peut restreindre les lignes selon l'utilisateur authentifié.
Spécification OpenAPI
Chaque instance PostgREST expose une spécification OpenAPI 3.0 à jour à son URL racine (GET /). Utilisez-la pour :
- l'importer dans Postman ou Insomnia pour vos tests ;
- générer des SDK clients typés avec openapi-generator ;
- alimenter des outils de documentation comme Swagger UI.