From 89cb79725006625665ea0a74b22fff8bd9fe9ce1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julius=20H=C3=A4rtl?= <jus@bitgrid.net>
Date: Mon, 5 Nov 2018 19:01:15 +0100
Subject: [PATCH] More api docs
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 | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/docs/API.md b/docs/API.md
index 77060635b..0a32e06fd 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -29,12 +29,31 @@ In any case a user doesn't have access to a requested entity, a 403 error will b
 }
 ```
 
+## Headers
+
+### If-Modified-Since
+
+Some index endpoints support limiting the result set to entries that have been changed since the given time.
+
+Example curl request:
+
+```bash
+curl -u admin:admin -X GET \
+    'http://localhost:8000/index.php/apps/deck/api/v1.0/boards/2/stacks' \
+    -H "OCS-APIRequest: true" \
+    -H "If-Modified-Since: Mon, 5 Nov 2018 09:28:00 GMT"
+```
+
 # Endpoints
 
 ## Boards
 
 ### GET /boards - Get a list of boards
 
+#### Headers
+
+The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time.
+
 #### Response
 
 ##### 200 Success
@@ -262,6 +281,11 @@ Returns an array of board items
 
 ### GET /board/{boardId}/stacks - Get stacks
 
+#### Headers
+
+The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time.
+
+
 #### Request parameters
 
 | Parameter | Type    | Description                  |
@@ -270,6 +294,20 @@ Returns an array of board items
 
 #### Response
 
+```json
+[
+  {
+    "title": "ToDo",
+    "boardId": 2,
+    "deletedAt": 0,
+    "lastModified": 1541426139,
+    "cards": [...],
+    "order": 999,
+    "id": 4
+  }
+]
+```
+
 ##### 200 Success
 
 ### GET /board/{boardId}/stacks/archived - Get list of archived stacks
@@ -282,6 +320,20 @@ Returns an array of board items
 
 #### Response
 
+```json
+[
+  {
+    "title": "ToDo",
+    "boardId": 2,
+    "deletedAt": 0,
+    "lastModified": 1541426139,
+    "cards": [...],
+    "order": 999,
+    "id": 4
+  }
+]
+```
+
 ##### 200 Success
 
 ### GET /board/{boardId}/stacks/{stackId} - Get stack details
@@ -318,6 +370,13 @@ Returns an array of board items
 | boardId   | Integer | The id of the board the stack belongs to |
 | stackId   | Integer | The id of the stack                      |
 
+#### Request body
+
+| Parameter | Type    | Description                                          |
+| --------- | ------- | ---------------------------------------------------- |
+| title     | String  | The title of the new stack                           |
+| order     | Integer | Order for sorting the stacks                         |
+
 #### Response
 
 ##### 200 Success
@@ -360,6 +419,18 @@ Returns an array of board items
 | boardId   | Integer | The id of the board the card belongs to |
 | stackId   | Integer | The id of the stack the card belongs to |
 
+#### Request body
+
+| Parameter | Type    | Description                                          |
+| --------- | ------- | ---------------------------------------------------- |
+| title     | String  | The title of the new stack                           |
+| type      | String  | Type of the card (for later use) use 'plain' for now |
+| 
+     
+     | Integer | Order for sorting the stacks                         |
+
+
+
 #### Response
 
 ##### 200 Success