Skip to main content
View as Markdown

CRUD et upsert des enregistrements

Cette page couvre les opérations de cycle de vie d'un enregistrement unique : créer, lire, mettre à jour, supprimer et upsert. Pour lister de nombreux enregistrements, voir Filtrage, tri et pagination ; pour les écritures en masse, voir Opérations en lot. Tous les corps d'écriture utilisent l'enveloppe canonique { "fields": { ... } } décrite dans la vue d'ensemble des enregistrements.

Créer un enregistrement

POST /api/tables/contacts/records
{
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}
Statut Signification
201 Created Enregistrement créé ; le corps est l'enregistrement stocké avec id et auteur
400 Bad Request Champ requis manquant, valeur de type de champ invalide ou violation de contrainte d'unicité
401 Unauthorized Aucune session active
404 Not Found La table n'existe pas (ou l'appelant n'y a pas accès)

La réponse porte l'id généré, l'écho des fields et les métadonnées d'auteur (createdBy, createdAt, updatedAt).

Lire un enregistrement

GET /api/tables/contacts/records/42
Statut Signification
200 OK Enregistrement renvoyé
401 Unauthorized Aucune session active
404 Not Found Enregistrement absent ou non visible par l'appelant (anti-énumération)

Les champs pour lesquels l'appelant n'a pas la permission de lecture sont omis de la réponse — le même enregistrement peut renvoyer un ensemble de champs différent selon le rôle de l'appelant et les permissions au niveau des champs.

Mettre à jour un enregistrement

PATCH effectue une mise à jour partielle : seuls les champs présents dans le corps sont écrits ; les champs omis sont laissés intacts.

PATCH /api/tables/contacts/records/42
{
  "fields": {
    "status": "active"
  }
}
Statut Signification
200 OK Enregistrement mis à jour ; updatedBy/updatedAt réestampillés
400 Bad Request Valeur de type de champ invalide ou violation de contrainte
401 Unauthorized Aucune session active
404 Not Found Enregistrement absent ou non visible
409 Conflict Échec du verrouillage optimiste (écriture obsolète)

Verrouillage optimiste

Incluez un jeton updatedAt de premier niveau à côté de fields pour vous prémunir contre les mises à jour perdues. Le serveur le compare à la colonne updated_at stockée et rejette une écriture divergente avec 409 Conflict.

PATCH /api/tables/contacts/records/42
{
  "fields": { "status": "active" },
  "updatedAt": "2025-01-15T10:30:00Z"
}

Supprimer un enregistrement

Par défaut, DELETE est une suppression réversible : il renseigne deletedAt/deletedBy et laisse la ligne récupérable.

DELETE /api/tables/contacts/records/42
DELETE /api/tables/contacts/records/42?permanent=true
Statut Signification
200 OK / 204 No Content Enregistrement supprimé de façon réversible (ou définitivement avec ?permanent=true)
401 Unauthorized Aucune session active
403/404 L'appelant n'a pas la permission de suppression, ou l'enregistrement n'est pas visible

La suppression définitive (?permanent=true) requiert la permission permanentDelete et est irréversible. Voir Suppression réversible et restauration pour la corbeille, la restauration et le comportement en cascade sur les enregistrements associés.

Upsert d'un enregistrement

L'upsert crée un enregistrement ou met à jour un enregistrement existant correspondant à un ou plusieurs champs uniques, en un seul appel. Utilisez matchFields (alias : fieldsToMergeOn) pour nommer la ou les clés de fusion.

POST /api/tables/contacts/records/upsert
{
  "fields": {
    "email": "john@example.com",
    "name": "John Doe",
    "status": "active"
  },
  "matchFields": ["email"]
}

La réponse indique si la ligne a été created (créée) ou updated (mise à jour) :

{
  "id": 123,
  "operation": "created",
  "record": {
    "id": 123,
    "email": "john@example.com",
    "name": "John Doe",
    "status": "active"
  }
}

Lorsqu'une ligne existante correspond aux matchFields, operation vaut "updated" à la place et la ligne correspondante est mise à jour. L'upsert est idéal pour la synchronisation idempotente depuis des systèmes externes — voir Opérations en lot pour la variante upsert multi-enregistrements.

Mise en forme d'affichage vs brute

Le paramètre de requête format contrôle la manière dont les valeurs des champs sont sérialisées sur les points de terminaison de lecture.

format Comportement
raw (défaut) Valeurs stockées, inchangées — préféré pour les clients programmatiques
display Valeurs lisibles par un humain : devises, dates, durées et noms d'affichage des pièces jointes mis en forme 
GET /api/tables/orders/records?format=display&timezone=Europe/Paris

La mise en forme est pilotée par type de champ :

Type de champ Mise en forme d'affichage
currency Symbole, nombre de décimales et séparateurs selon la locale
datetime Format date/heure configuré ; ?timezone= (IANA) remplace le fuseau horaire de rendu
duration h:mm, h:mm:ss ou heures décimales selon la configuration du champ
attachment / multiple-attachments URL plus métadonnées et noms d'affichage
json Sérialisé selon la configuration du champ et le paramètre format

Pages associées