Utiliser l’en-tête HTTP If-Match dans les opérations PUT et PATCH

Pour les points de terminaison REST, les développeurs veulent souvent contrôler si les mises à jour créent de nouveaux enregistrements ou modifient uniquement les enregistrements existants. L’en-tête If-Match HTTP fournit ce contrôle dans le Générateur d’API de données (DAB).

Par défaut, DAB traite PUT et PATCH comme des opérations upsert :

• Si la ressource existe : DAB la met à jour.

• S’il n’existe pas : DAB l’insère.

  • PUT → full upsert (remplace la ressource).
  • PATCH → upsert incrémentiel (applique une mise à jour partielle).

Ajout de If-Match: * modifications de ce comportement à la sémantique de mise à jour uniquement.

Que fait If-Match dans DAB

If-Match est pris en charge uniquement avec la valeur *générique .

Vue d’ensemble du comportement

• DAB n’implémente pas la correspondance par enregistrement ETag ou version.
• Aucun jeton d’accès concurrentiel n’est évalué. * affirme uniquement « doit exister ».
• S’applique uniquement à REST, et non à GraphQL.
• Actuellement non significatif pour les opérations DELETE.

Utilisation de If-Match avec PUT

Sans If-Match, PUT insère lorsque la ressource n’existe pas (retourne 201 Created).

Exemple de mise à jour uniquement

Requête

PUT /api/Books/id/1
If-Match: *
Content-Type: application/json

{
  "title": "The Return of the King",
  "publisher_id": 7
}

Réussite (enregistrement existait)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "title": "The Return of the King",
  "publisher_id": 7
}

Échec (enregistrement manquant)

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "No Update could be performed, record not found"
}

Exemple d’insertion Upsert (aucun If-Match et enregistrement n’existait pas)

Requête

PUT /api/Books/id/500
Content-Type: application/json

{
  "title": "Inserted via PUT",
  "publisher_id": 7
}

Réponse

HTTP/1.1 201 Created
Location: id/500
Content-Type: application/json

{
  "id": 500,
  "title": "Inserted via PUT",
  "publisher_id": 7
}

Utilisation de If-Match avec PATCH

PATCH se comporte de la même façon. Sans If-Match, il effectue un upsert incrémentiel. Avec If-Match: *, il met uniquement à jour les lignes existantes.

Requête

PATCH /api/Books/id/1
If-Match: *
Content-Type: application/json

{
  "title": "The Two Towers"
}

Réponse en cas de réussite

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "title": "The Two Towers"
}

Réponse lorsqu’elle est introuvable

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "No Update could be performed, record not found"
}

Utilisation de If-Match non valide

Toute valeur autre que * (y compris les chaînes entre guillemets) est rejetée.

Requête

PUT /api/Books/id/1
If-Match: "abc123"
Content-Type: application/json

{
  "title": "To Kill a Mockingbird"
}

Réponse

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Etags not supported, use '*'"
}

Révision

• Omettez If-Match la sémantique upsert (insert-or-update).
• Utiliser If-Match: * pour une sémantique de mise à jour uniquement stricte (404 si l’élément est manquant).
• N’utilisez aucune autre valeur. La correspondance ETag réelle n’est pas implémentée.