From d64ae9bef2a93591020b15014a4918c20780e5f8 Mon Sep 17 00:00:00 2001
From: Hank Grabowski <hankgrabowski@gmail.com>
Date: Wed, 22 Feb 2023 22:35:24 -0500
Subject: [PATCH] Add new Friendica Photo Album GET endpoints to documentation

---
 doc/API-Entities.md  | 34 +++++++++++++++++
 doc/API-Friendica.md | 88 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 120 insertions(+), 2 deletions(-)

diff --git a/doc/API-Entities.md b/doc/API-Entities.md
index 6c3e94a39..0242f4ab0 100644
--- a/doc/API-Entities.md
+++ b/doc/API-Entities.md
@@ -1170,6 +1170,40 @@ Mutually exclusive with <code>link</code>.
 </tbody>
 </table>
 
+
+## Photo Album
+
+<table class="table table-condensed table-striped table-bordered">
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+
+<tr>
+<td><code>name</code></td>
+<td>String</td>
+<td>The name of the photo album</td>
+</tr>
+
+<tr>
+<td><code>created</code></td>
+<td>String (Date)</td>
+<td>The creation date of the album. Format <code>YYYY-MM-DD HH:MM:SS</code></td>
+</tr>
+
+<tr>
+<td><code>count</code></td>
+<td>Integer</td>
+<td>The number of images in the album</td>
+</tr>
+
+</tbody>
+</table>
+
 ## Private message
 
 <table class="table table-condensed table-striped table-bordered">
diff --git a/doc/API-Friendica.md b/doc/API-Friendica.md
index 4e640c288..ea11c793a 100644
--- a/doc/API-Friendica.md
+++ b/doc/API-Friendica.md
@@ -665,8 +665,8 @@ On success:
 
 ```json
 {
-    "result": "updated",
-    "message":"album 'abc' with all containing photos has been renamed to 'xyz'."
+  "result": "updated",
+  "message":"album 'abc' with all containing photos has been renamed to 'xyz'."
 }
 ```
 
@@ -676,8 +676,92 @@ On error:
 * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
 * 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
 
+### GET api/friendica/photoalbums
+
+Get a list of photo albums for the user
+
+#### Parameters
+
+None 
+#### Return values
+
+On success a list of photo album objects:
+
+```json
+[
+  {
+	"name": "Wall Photos",
+	"created": "2023-01-22 02:03:19",
+	"count": 4
+  },
+  {
+	"name": "Profile photos",
+	"created": "2022-11-20 14:40:06",
+	"count": 1
+  }
+]
+```
+
+### GET api/friendica/photoalbum
+
+Get a list of images in a photo album
+#### Parameters
+
+* `album` (Required): name of the album to be deleted
+* `limit` (Optional): Maximum number of items to get, defaults to 50, max 500
+* `offset`(Optional): Offset in results to page through total items, defaults to 0
+* `latest_first` (Optional): Reverse the order so the most recent images are first, defaults to false
+
+#### Return values
+
+On success:
+
+* JSON return with the list of Photo items
+
+**Example:**
+`https://<server>/api/friendica/photoalbum?album=Wall Photos&limit=10&offset=2`
+
+```json
+[
+  {
+	"created": "2023-02-14 14:31:06",
+	"edited": "2023-02-14 14:31:14",
+	"title": "",
+	"desc": "",
+	"album": "Wall Photos",
+	"filename": "image.png",
+	"type": "image/png",
+	"height": 835,
+	"width": 693,
+	"datasize": 119523,
+	"profile": 0,
+	"allow_cid": "",
+	"deny_cid": "",
+	"allow_gid": "",
+	"deny_gid": "",
+	"id": "899184972463eb9b2ae3dc2580502826",
+	"scale": 0,
+	"media-id": 52,
+	"scales": [
+	  {
+		"id": 52,
+		"scale": 0,
+		"link": "https://<server>/photo/899184972463eb9b2ae3dc2580502826-0.png",
+		"width": 693,
+		"height": 835,
+		"size": 119523
+	  },
+	  ...
+	],
+	"thumb": "https://<server>/photo/899184972463eb9b2ae3dc2580502826-2.png"
+  },
+  ...
+]
+```
+
 ---
 
+
 ### GET api/friendica/profile/show
 
 Returns the [Profile](help/API-Entities#Profile) data of the authenticated user.