From 6a8e607134c071d6ac6a97b9e8e2b309c6e69d32 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julius=20H=C3=A4rtl?= <jus@bitgrid.net>
Date: Tue, 10 Nov 2020 17:14:35 +0100
Subject: [PATCH] Add documentation for ETags
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Julius Härtl <jus@bitgrid.net>
---
 docs/API.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/API.md b/docs/API.md
index c87ba22c6..11f661145 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -69,6 +69,31 @@ curl -u admin:admin -X GET \
     -H "If-Modified-Since: Mon, 05 Nov 2018 09:28:00 GMT"
 ```
 
+### ETag
+
+An ETag header is returned in order to determine if further child elements have been updated for the following endpoints:
+
+- Fetch all user board `GET /api/v1.0/boards`
+- Fetch a single board `GET /api/v1.0/boards/{boardId}`
+- Fetch all stacks of a board `GET /api/v1.0/boards/{boardId}/stacks`
+- Fetch a single stacks of a board `GET /api/v1.0/boards/{boardId}/stacks/{stackId}`
+- Fetch a single card of a board `GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}`
+- Fetch attachments of a card `GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments`
+
+If a `If-None-Match` header is provided and the requested element has not changed a `304` Not Modified response will be returned. 
+
+Changes of child elements will propagate to their parents and also cause an update of the ETag which will be useful for determining if a sync is necessary on any client integration side. As an example, if a label is added to a card, the ETag of all related entities (the card, stack and board) will change.
+
+If available the ETag will also be part of JSON response objects as shown below for a card:
+
+```json
+{
+  "id": 81,
+  "ETag": "bdb10fa2d2aeda092a2b6b469454dc90",
+  "title": "Test card"
+}
+```
+
 # Changelog
 
 ## 1.0.0 (unreleased)