api: Document Item.author field and make it nullable

This raises API version, since previously the value would be an empty string when there was no author.

Also update the database contents, replacing empty authors with `null`, so that clients can just rely on `null` author meaning ”no author”.

Author: jtojnar

NEWS.md

@@ -59,6 +59,7 @@
   - `GET /login` endpoint, use `POST /login`. ([#1360](https://github.com/fossar/selfoss/pull/1360))
   - `GET /logout` was deprecated in favour of newly introduced (*API 4.1.0*) `DELETE /api/session/current`. ([#1360](https://github.com/fossar/selfoss/pull/1360))
   - `POST /source/delete/:id` in favour of `DELETE /source/:id`. ([#1360](https://github.com/fossar/selfoss/pull/1360))
+- *API 6.0.0*: Makes the `author` field `null` when an item author is not known ([#1367](https://github.com/fossar/selfoss/pull/1367))
 
 ### Customization changes
 - `selfoss.shares.register` was removed. Instead you should set `selfoss.customSharers` to an object of *sharer* objects. The `action` callback is now expected to open a window on its own, instead of returning a URL. A label and a HTML code of an icon (you can use a `<img>` tag, inline `<svg>`, emoji, etc.) are now expected.

assets/js/templates/Item.jsx

@@ -472,7 +472,7 @@ export default function Item({ currentTime, item, selected, expanded, setNavExpa
             <span className="entry-separator">•</span>
 
             {/* author */}
-            {author.trim() !== '' ?
+            {author !== null ?
                 <React.Fragment>
                     <span className="entry-author">{author}</span>
                     <span className="entry-separator">•</span>

docs/api-description.json

@@ -3,7 +3,7 @@
   "servers": [],
   "info": {
     "description": "You can access selfoss by using the same backend as selfoss user interface: The RESTful HTTP JSON API. There are a few urls where you can get information from selfoss and some for updating data. Assume you want all tags for rendering this in your own app. You have to make an HTTP GET call on the url /tags:\n\n```\nGET http://yourselfossurl.com/tags\n```\nThe result is following JSON formatted response (in this example two tags “blog” and “deviantart” are available:\n\n```\n[{\"tag\":\"blog\",\"color\":\"#251f10\",\"unread\":\"1\"},\n{\"tag\":\"deviantart\",\"color\":\"#e78e5c\",\"unread\":\"0\"}]\n```\n\nFollowing docs shows you which calls are possible and which response you can expect.",
-    "version": "5.0.0",
+    "version": "6.0.0",
     "title": "selfoss"
   },
   "tags": [
@@ -954,6 +954,12 @@
             "type": "string",
             "example": "\n<p>Das 1-GBit/s-Angebot Google Fiber kommt nach Austin, die Hauptstadt des US-Bundesstaates Texas..."
           },
+          "author": {
+            "description": "Name/e-mail of the author of the item/article/tweet, when available.",
+            "type": "string",
+            "nullable": true,
+            "example": "William Miller"
+          },
           "unread": {
             "description": "true when the article is marked as unread, false when the article is marked as read",
             "type": "boolean",

docs/content/docs/customization/api.md

@@ -11,7 +11,7 @@ Since selfoss 2.19, the API follows [semantic versioning](https://semver.org/) d
 
 | selfoss | API |
 |---|---|
-| [2.19] | [5.0.0] |
+| [2.19] | [6.0.0] |
 
 [2.19]: https://github.com/fossar/selfoss/releases/tag/2.19
-[5.0.0]: https://app.swaggerhub.com/apis-docs/jtojnar/selfoss/5.0.0
+[6.0.0]: https://app.swaggerhub.com/apis-docs/jtojnar/selfoss/6.0.0

src/constants.php

@@ -7,4 +7,4 @@
 // independent of selfoss version
 // needs to be bumped each time public API is changed (follows semver)
 // keep in sync with docs/api-description.json
-const SELFOSS_API_VERSION = '5.0.0';
+const SELFOSS_API_VERSION = '6.0.0';

src/daos/mysql/Database.php

@@ -287,6 +287,14 @@ public function __construct(DatabaseConnection $connection, Logger $logger) {
             $this->exec('INSERT INTO ' . $this->connection->getTableNamePrefix() . 'version (version) VALUES (13)');
             $this->commit();
         }
+        if ($version < 14) {
+            $this->logger->debug('Upgrading database schema to version 14');
+
+            $this->beginTransaction();
+            $this->exec('UPDATE ' . $this->connection->getTableNamePrefix() . "items SET author = NULL WHERE author = ''");
+            $this->exec('INSERT INTO ' . $this->connection->getTableNamePrefix() . 'version (version) VALUES (14)');
+            $this->commit();
+        }
     }
 
     /**

src/daos/pgsql/Database.php

@@ -265,6 +265,14 @@ public function __construct(DatabaseConnection $connection, Logger $logger) {
             $this->exec('INSERT INTO version (version) VALUES (13)');
             $this->commit();
         }
+        if ($version < 14) {
+            $this->logger->debug('Upgrading database schema to version 14');
+
+            $this->beginTransaction();
+            $this->exec("UPDATE items SET author = NULL WHERE author = ''");
+            $this->exec('INSERT INTO version (version) VALUES (14)');
+            $this->commit();
+        }
     }
 
     /**

src/daos/sqlite/Database.php

@@ -283,6 +283,14 @@ public function __construct(DatabaseConnection $connection, Logger $logger) {
             $this->exec('INSERT INTO version (version) VALUES (13)');
             $this->commit();
         }
+        if ($version < 14) {
+            $this->logger->debug('Upgrading database schema to version 14');
+
+            $this->beginTransaction();
+            $this->exec("UPDATE items SET author = NULL WHERE author = ''");
+            $this->exec('INSERT INTO version (version) VALUES (14)');
+            $this->commit();
+        }
     }
 
     /**

src/helpers/ContentLoader.php

@@ -212,7 +212,7 @@ public function fetch($source) {
                     'datetime' => $itemDate->format('Y-m-d H:i:s'),
                     'uid' => $item->getId(),
                     'link' => htmLawed($item->getLink(), ['deny_attribute' => '*', 'elements' => '-*']),
-                    'author' => $item->getAuthor() ?: '',
+                    'author' => $item->getAuthor(),
                     'thumbnail' => null,
                     'icon' => null,
                 ];