diff options
Diffstat (limited to 'search/search_index.json')
| -rw-r--r-- | search/search_index.json | 1 |
1 files changed, 1 insertions, 0 deletions
diff --git a/search/search_index.json b/search/search_index.json new file mode 100644 index 000000000..cbe6b1528 --- /dev/null +++ b/search/search_index.json @@ -0,0 +1 @@ +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"<p>Welcome to the Nextcloud News APP documentation, it contains information for users, administrators and developers. News is an APP for Nextcloud that can be installed from the official APP Store.</p> <p>News offers the user an RSS/Atom feed reader and can be used to subscribe to multiple feeds, which get automatically updated in the background. Additionally, news offers a REST-API that allows clients to synchronize with News.</p>"},{"location":"admin/","title":"Admin","text":"<p>Welcome to the Admin documentation this page explains some of the configuration options for news.</p>"},{"location":"admin/#system-cron","title":"System Cron","text":"<p>Nextcloud uses cron to run regular jobs, News relies on the Job system to execute the feed updates. Alternatively you may use an external updater, in this case you need to disable the system cron in the settings.</p>"},{"location":"admin/#auto-purge-count","title":"Auto purge count","text":"<ul> <li>The default value is 200.</li> <li>To disable this feature, use -1.</li> <li>Unread and starred items are not deleted.</li> </ul> <p>Auto purging automatically removes the oldest read items of every feed after every update. The value you enter here is used as the limit of read items per feed, unless the feed comes with more items in it's feed. The individual limit per feed is only adjusted when it's bigger. Let's say last feed update came with 210 items, then that will be the limit for that feed as long as no bigger update with more items is fetched. In this case the limit will be 210 instead of 200, for that feed.</p> <p>This is needed to prevent items from reappearing in the feed.</p>"},{"location":"admin/#purge-unread-items","title":"Purge unread items","text":"<p>This changes the behavior of the auto purging to also purge unread items. This is useful if you have users with a lot of unread items.</p> <p>Starred items are always kept.</p>"},{"location":"admin/#explore-service","title":"Explore Service","text":"<p>If you are using the News app in your company/community, it might be interesting to offer your users a bunch of easily to discover default feeds. You could also create a website where people can add and up-vote news feeds like bigger cloud feed readers like Feedly do it or even convert their APIs into a service for the News app (if someone wants to provide one for the News app, feel free to contact us by creating an issue in the bug tracker).</p> <p>The URL should be a path to a directory which contains a JSON file in the format of feeds.LANG_CODE.json where LANG_CODE is a two character language code (e.g. en or de).</p> <p>For example, entering the URL https://domain.com/directory as explore URL will produce the following request for German users:</p> <pre><code>GET https://domain.com/directory/feeds.de.json\n</code></pre> <p>Do not forget to implement CORS in your API, otherwise the request will fail!</p>"},{"location":"admin/#update-interval","title":"Update Interval","text":"<p>The update interval is used to determine when the next update of all feeds should be done. By default, the value is set to 3600 seconds (1 hour) You can configure this interval as an administrator. The new value is only applied after the next run of the updater.</p>"},{"location":"admin/#what-is-a-good-update-interval","title":"What is a good update interval?","text":"<p>That depends on your individual needs. Please keep in mind that the lower you set your update interval, the more traffic is generated.</p>"},{"location":"admin/#can-i-set-individual-update-intervals-per-feeduser","title":"Can I set individual update intervals per feed/user?","text":"<p>No, that is not possible.</p>"},{"location":"clients/","title":"Clients","text":"<p>Clients are applications that use the REST API of News. They are not maintained by the News team. If you are the developer of an app, feel free to create a PR to add your app to this list.</p>"},{"location":"clients/#sync-clients","title":"Sync Clients","text":"<p>A sync client can be used to read news and synchronize via the API.</p> Name OS/Platform License Source RSS Guard Windows, Linux, OS/2, macOS GPL-3.0 License GitHub Fluent Reader Windows, Linux, macOS BSD-3-Clause License GitHub Communique Linux LGPL-2.1 License GitHub NewsFlash Linux GPL-3.0 License GitLab Nextcloud News Reader Android GPL-3.0 License GitHub OCReader Android GPL-3.0 License GitHub Newsout Android Apache-2.0 License GitHub Readrops Android GPL-3.0 License GitHub CloudNews iOS BSD-2-Clause License GitHub Fiery Feeds iOS, macOS - - Nextnews iOS - - News Checker Google Chrome - GitHub own News Blackberry - - FeedSpider Firefox OS, webOS, LuneOS MIT License GitHub fastReader Windows Phone - - py3status i3wm BSD-3-Clause License GitHub newsboat Unix Terminal MIT License GitHub Newsie Ubuntu Touch GPL-3.0 License GitLab Fuoten Sailfish OS GPL-3.0 License GitHub"},{"location":"clients/#update-clients","title":"Update Clients","text":"<p>An update client uses the News API or the OCC CLI to update the feeds in News.</p> <ul> <li>Python multithread updater</li> </ul>"},{"location":"developer/","title":"Developer","text":"<p>Welcome to the Nextcloud News App developer documentation.</p> <p>News is open for contributions, if you plan to implement a new feature make sure to open a discussion. Describe the feature that you are planing and your first idea how to implement it. This ensures that you don't start working on something which collides with the targets of the maintainers.</p> <p>For small fixes and improvements feel free to directly create a PR, the maintainers are happy to review your code.</p>"},{"location":"developer/#apis","title":"APIs","text":"<p>News offers an API that can be used by clients to synchronize with the server. There are two API declarations, so far only V1 has been fully implemented. Work on V2 has started with low priority.</p> <ul> <li>API-V1.2</li> <li>API-V1.3</li> <li>API-V2</li> </ul>"},{"location":"developer/#coding-style-guidelines","title":"Coding Style Guidelines","text":"<p>The PHP code should all adhere to PSR-2. Note that this is a different codestyle than Nextcloud itself uses. To test the codestyle you can run <code>make phpcs</code>.</p> <p>The application Front End uses Vue 2.7 and the Nextcloud Libraries Vue Components for building the Application running inside your Nextcloud instance. For linting these files, we are using eslint, see the config file. We also have Unit Tests for the components that run with Jest, please ensure these pass when adding new features/fixing bugs.</p>"},{"location":"developer/#general-developer-setup","title":"General Developer setup","text":"<p>Check the Nextcloud documentation to learn how to setup a developer environment, alternatively to a proper web server you can also use the builtin php server on demand, it is enough for development purposes.</p> <p>When your setup is running, clone the news repository in the <code>apps/</code> directory inside the server.</p> <p>Change into the news directory and run <code>make</code> to build the app, you will need php, composer, node, npm and maybe more.</p> <p>Now you can basically use the news app and test any changes you make on your local development environment. Check out the <code>appinfo/routes.php</code> file and <code>lib/controller/</code> directory for details on API controllers. Or check out <code>package.json</code> for npm scripts and the <code>src/</code> directory for the front end Vue Application.</p>"},{"location":"developer/#frontend-tipsorganization","title":"Frontend Tips/Organization","text":"<ul> <li>We use the Nextcloud Vue component library for most of the form controls and navigation</li> <li>Vuex is used for state management, this is similar to Redux and has Actions/Mutations and Getters</li> <li>We are using the Nextcloud Webpack Vue configuration and have enabled Typescript support and importing in the Vue components</li> <li>We use ESLint and StyleLint for ensuring correct formatting of the Scripts and HTML</li> </ul>"},{"location":"developer/#testing","title":"Testing","text":"<p>Please make sure to run all tests before submitting any pull requests.</p>"},{"location":"developer/#frontend-unit-tests","title":"Frontend Unit Tests","text":"<p>Frontend unit tests are written with Jest and can be run with <code>npm run test</code>.</p>"},{"location":"developer/#api-and-cli-integration-tests","title":"API and CLI Integration Tests","text":"<p>We use bats to run integration tests against the API and the cli.</p> <p>Check how to install bats on your system in the official documentation.</p> <p>You also need to pull the submodules of the news repo.</p> <pre><code>git submodules update --init\n</code></pre> <p>The cli tests expect that the feeds are reachable at <code>http://localhost:8090</code>, to achieve that you can use <code>make feed-server &</code> the <code>&</code> means it'll run in the background.</p> <p>Now the test feeds will be reachable for bats. Run the tests by executing <code>bats tests/command</code> you can also only run specific tests for example <code>bats tests/command/feeds.bats</code>.</p> <p>For the API tests you need to run a second php server or have another web server that provides Nextcloud and the News App. The tests expect to find Nextcloud at <code>http://localhost:8080</code> You can do this by running <code>make nextcloud-server</code>.</p> <p>The bats tests can be executed like this <code>bats tests/api</code>.</p>"},{"location":"install/","title":"Installation/Update & Uninstall","text":""},{"location":"install/#dependencies","title":"Dependencies","text":"<ul> <li>64bit OS (starting with News 16.0.0)</li> <li>PHP >= 8.0</li> <li>Nextcloud (current stable version)</li> <li>libxml >= 2.7.8</li> </ul> <p>You also need some PHP extensions:</p> <ul> <li>json</li> <li>simplexml</li> <li>xml</li> <li>dom</li> <li>curl</li> <li>iconv</li> </ul>"},{"location":"install/#supported-databases","title":"Supported Databases","text":"<ul> <li>PostgreSQL >= 10</li> <li>MariaDB >= 10.2</li> <li>MySQL >= 8.0</li> <li>SQLite (discouraged)</li> </ul> <p>Also see the Nextcloud documentation. Oracle is currently not supported by News.</p>"},{"location":"install/#performance-notices","title":"Performance Notices","text":"<ul> <li>Use MySQL/MariaDB or PostgreSQL for better database performance</li> <li>Use the updater script to thread and speed up the update</li> </ul>"},{"location":"install/#cache","title":"Cache","text":"<p>News and it's libraries require a writeable temporary directory used as cache. The base directory depends on your system. You can configure a custom directory if you want.</p> <p>In most cases the base directory will be <code>/tmp</code>. News will create a folder <code>news-$instanceID</code> the instance ID is defined by Nextcloud.</p> <p>Inside that folder a subfolder <code>cache</code> is created, inside this cache folder news and libraries will try to create cache directories for caching images, html and more.</p> <p>You need to ensure that your web-server user can write to that directory.</p>"},{"location":"install/#before-you-installupdate-the-news-app","title":"Before you install/update the News app","text":"<p>Before you install the app do the following:</p> <ul> <li>Check that your installation fulfills the requirements listed above</li> <li>Set up Nextcloud Background Jobs to enable feed updates.</li> </ul> <p>Then proceed to install the app either from an archive (zip/tar.gz) or clone it from the repository using git</p>"},{"location":"install/#installing-from-the-app-store","title":"Installing from the app store","text":"<p>This is the easiest solution: Simply go the apps page (section: \"Multimedia\") and enable the News app</p>"},{"location":"install/#installing-from-archive","title":"Installing from archive","text":"<ul> <li>Go to the Nextcloud News GitHub releases page and download the latest release/archive to your server</li> <li>The news.tar.gz file contains the compiled and signed app files, if you install from source you have to build the app on your own.</li> <li>On your server, check if there is a folder called nextcloud/apps/news. If there is one, delete it.</li> <li>Extract the downloaded archive to the nextcloud/apps/ folder.</li> <li>Remove the version from the extracted folder (e.g. rename nextcloud/apps/news-4.0.3/ to nextcloud/apps/news/</li> <li> <p>If you are a version greater than or equal to 8.0.0 and downloaded the Source code zip or tar.gz, you need to install the JavaScript and PHP dependencies and compile the JavaScript first. On your terminal, change into the nextcloud/apps/news/ directory and run the following command (requires node >5.6, npm, curl, make and which):</p> <pre><code>sudo -u www-data make # www-data might vary depending on your distribution\n</code></pre> </li> <li> <p>Finally make sure that the nextcloud/apps/news directory is owned by the web server user</p> <pre><code>sudo chown -R www-data:www-data nextcloud/apps/news # www-data:www-data might vary depending on your distribution\n</code></pre> </li> <li> <p>Activate the News app in the apps menu</p> </li> </ul>"},{"location":"install/#installing-from-git-development-version","title":"Installing from Git (development version)","text":""},{"location":"install/#build-dependencies","title":"Build Dependencies","text":"<p>These Dependencies are only relevant if you want to build the source code:</p> <ul> <li>make</li> <li>which</li> <li>Node.js >= 6</li> <li>npm</li> <li> <p>composer</p> </li> <li> <p>The master branch will always be stable in conjunction with the latest master branch from Nextcloud</p> </li> <li>JavaScript and PHP libraries are not included anymore since 8.0.0 and will require you to run make after updating/installing the app</li> <li> <p>In your terminal go into the nextcloud/apps/ directory and then run the following command:</p> <pre><code>git clone https://github.com/nextcloud/news.git\ncd news\nmake\n</code></pre> </li> <li> <p>If you are using a stable Nextcloud release, stay with the latest git tag release which is running on your version. To get an overview over all existing tags run:</p> <pre><code>git tag\n</code></pre> </li> </ul> <p>You can switch to a release which will be supported on your installation by running:</p> <pre><code> git checkout tags/TAG\n make # if News version >= 8.0.0\n</code></pre> <p>For instance, to use the 5.2.8 release, run:</p> <pre><code> git checkout tags/5.2.8\n</code></pre> <ul> <li>Activate the News app in the apps menu</li> </ul> <p>To update the News app use change into the nextcloud/apps/news/ directory using your terminal and then run:</p> <pre><code>git pull --rebase origin master\nmake\n</code></pre>"},{"location":"install/#uninstall-with-cleanup","title":"Uninstall with cleanup","text":"<p>First uninstall the app via the web-interface or via occ:</p> <pre><code>./occ app:remove news\n</code></pre> <p>This currently does not remove any of the database tables. Data in your <code>/tmp</code> directory will be automatically deleted by the OS. If you changed the temporary directory for Nextcloud you need to check on your own.</p> <p>Careful, this next part is only intended for admins, that know what they are doing.</p> <p>To remove the tables from the DB we drop the tables of News. Your installation might have a different prefix than <code>oc_</code> but it is the default in most installations. Connect to your DB and execute the commands. Don't forget to switch to the right database. For example in mysql: <code>use nextcloud;</code></p> <pre><code>DROP TABLE oc_news_items;\nDROP TABLE oc_news_feeds;\nDROP TABLE oc_news_folders;\n</code></pre> <p>Then we remove the traces in the migrations table.</p> <pre><code>DELETE FROM oc_migrations WHERE app='news';\n</code></pre> <p>Next delete the app configuration.</p> <pre><code>DELETE FROM oc_appconfig WHERE appid = 'news';\n</code></pre> <p>And finally remove the jobs from the job table. The last two lines are only needed for older installations.</p> <pre><code>DELETE FROM oc_jobs WHERE class='OCA\\\\News\\\\Cron\\\\UpdaterJob';\nDELETE FROM oc_jobs WHERE class='OCA\\\\News\\\\Cron\\\\Updater';\nDELETE FROM oc_jobs WHERE argument='[\"OCA\\\\\\\\News\\\\\\\\Cron\\\\\\\\Updater\",\"run\"]';\n</code></pre> <p>Now nothing is left from News in your Nextcloud installation.</p>"},{"location":"maintenance/","title":"Maintenance","text":""},{"location":"maintenance/#release","title":"Release","text":"<p>Releases are created automatically by GitHub Actions. A release is triggered via a GitHub Release. The GitHub Action will then start a build based on the git tag. A release can only be approved by @Grotax or @SMillerDev. An admin of the Nextcloud organization can always overwrite these settings. The private key is stored as environmental secret in GitHub. The owner of the private key is @Grotax.</p>"},{"location":"maintenance/#support","title":"Support","text":""},{"location":"maintenance/#php","title":"PHP","text":"<p>While the app should try to support all PHP versions that Nextcloud currently supports, the real focus when deciding to cut a PHP version should be on maintenance burden. Users are nice, but devs should be a priority in decisions that are likely to impact them significantly.</p>"},{"location":"maintenance/#issues","title":"Issues","text":"<ul> <li> <p>Bug reports without test cases (feed URL and action is enough) can be closed with or without comment.</p> </li> <li> <p>Feature requests without thoughtful commentary or pull request can be closed with or without comment, unless a developer is interested to support such a feature.</p> </li> <li> <p>Issues without activity in the last 30 days can be closed with or without comment. If this is a bug you care about that isn't getting attention, fix it. If you're good enough to understand the bug, you're good enough to fix it.</p> </li> </ul> <p>Largely inspired by https://gist.github.com/ryanflorence/124070e7c4b3839d4573</p>"},{"location":"troubleshooting/","title":"Troubleshooting","text":"<p>This is a brief list of common issues that come up with NextCloud News.</p>"},{"location":"troubleshooting/#my-browser-shows-a-mixed-content-warning-connection-is-not-secure","title":"My browser shows a mixed content warning (Connection is Not Secure)","text":"<p>If you are serving your Nextcloud over HTTPS your browser will very likely warn you with a yellow warnings sign about your connection not being secure.</p> <ul> <li>Chrome will show no green HTTPS lock sign.</li> <li>Firefox will show you the following image Mixed Passive Content </li> </ul> <p>Note that this warning is not red and won't block the page like the following images which signal a serious issue:</p> <ul> <li>Chrome </li> <li>Firefox </li> </ul>"},{"location":"troubleshooting/#what-is-the-cause-of-the-yellow-error-message","title":"What is the cause of the (yellow) error message?","text":"<p>This warning is caused by mixed passive content and means that your page loads passive resources from non HTTPS resources, such as:</p> <ul> <li>Images</li> <li>Video/Audio</li> <li>Some Ads</li> </ul> <p>This allows a possible attacker to perform a MITM (man-in-the-middle) attack by serving you different images or audio/video.</p>"},{"location":"troubleshooting/#why-doesnt-the-news-app-fix-it","title":"Why doesn't the News app fix it?","text":"<p>The News app fully prevents mixed active content by only allowing HTTPS iframes from known locations; other possible mixed active content elements such as <script\\> are stripped from the feed. Because images and audio/video are an integral part of a feed, we can not simply strip them.</p> <p>Since an attacker can not execute code in contrast to mixed active content, but only replace images/audio/video in your feed reader, this is not considered to be a security issue. If, for whatever reason (e.g. feed which would allow fishing), this is a security problem for you, contact the specific feed provider and ask him to serve his feed content over HTTPS.</p>"},{"location":"troubleshooting/#why-dont-you-simply-use-an-https-imageaudiovideo-proxy","title":"Why don't you simply use an HTTPS image/audio/video proxy?","text":"<p>For the same reason that we can't fix non HTTPS websites: It does not fix the underlying issue, but only silences it. If you are using an image HTTPS proxy, an attacker can simply attack your image proxy since the proxy fetches insecure content. Even worse: if your image proxy serves these images from the same domain as your Nextcloud installation, you are vulnerable to XSS via SVG images. In addition, people feel safe when essentially they are not.</p> <p>Since most people don't understand mixed content and don't have two domains and a standalone server for the image proxy, it is very likely they will choose to host it under the same domain.</p> <p>Because we care about our users' security and don't want to hide security warnings, we won't fix (aka silence) this issue.</p> <p>The only fix for this issue is that feed providers serve their content over HTTPS.</p>"},{"location":"troubleshooting/#i-am-getting-exception-someclass-does-not-exist-errors-in-my-nextcloudlog","title":"I am getting: Exception: Some\\Class does not exist errors in my nextcloud.log","text":"<p>This is very often caused by missing or old files, e.g. by failing to upload all the News app files or errors during installation. Before you report a bug, please recheck if all files from the archive are in place and accessible.</p>"},{"location":"troubleshooting/#feeds-not-updated","title":"Feeds not updated","text":"<p>Feeds can be updated using Nextcloud's system cron or an external updater via the API. The feed update is not run in Webcron and AJAX cron mode!</p>"},{"location":"troubleshooting/#validating-using-system-cron","title":"Validating Using System Cron","text":"<p>Info</p> <p>This requires Nextcloud 26 or newer and News 24.0.0 or newer.</p> <p>Follow this checklist:</p> <ul> <li>Check admin settings of Nextcloud, was the last cron execution ok.</li> <li>Check the logs for errors.</li> <li>Does your cache configuration work?</li> <li>Check the News admin settings, system cron is used to update news.</li> <li>You should see a info card at the top, which will tell you when the last job execution was.</li> <li>If the card is red it is very likely that the update job is stuck.</li> <li>If it is green then maybe only some feeds are failing to update, check the Nextcloud logs.</li> </ul> <p>If you believe the job is stuck you can reset it. For further steps you need to use occ.</p> <p>You can check again the status of the job. (replace <code>www-data</code> with your httpd user)</p> <pre><code>sudo -u www-data php ./occ news:updater:job\nChecking update Status\nLast Execution was 2023-03-20 12:20:03 UTC\n</code></pre> <p>The same check that is done in the News admin settings can be done using occ too. Adding the <code>--check-elapsed</code> option displays the time elapsed since the last execution, and if it's considered too long ago, a message will be displayed, and the command returns with exit code 2. This can be used in scripts to send an alert for example.</p> <pre><code>$ sudo -u www-data php ./occ news:updater:job --check-elapsed\nChecking update Status\nLast Execution was 2023-03-20 12:20:03 UTC\n8 hours, 21 minutes, 20 seconds ago\nSomething is wrong with the news cronjob, execution delay exceeded the configured interval.\n</code></pre> <p>If you think the job is stuck you can reset it, this may lead to issues if the job is currently running!</p> <pre><code>sudo -u www-data php ./occ news:updater:job --reset\nChecking update Status\nLast Execution was 2023-03-20 12:20:03 UTC\nAttempting to reset the job.\nDone, job should execute on next schedule.\n</code></pre> <p>The output of the command should have changed.</p> <pre><code>sudo -u www-data php ./occ news:updater:job\nChecking update Status\nLast Execution was 1970-01-01 00:00:00 UTC\n</code></pre> <p>After some time has passed the timestamp should be close to the current time.</p> <p>If this did not help, check the logs and open a issue or discussion on GitHub.</p>"},{"location":"troubleshooting/#outdated-steps","title":"Outdated Steps","text":"<p>Follow these steps if you are running an older version of News and Nextcloud.</p> <ul> <li>Check if you are using the system cron (Cron) setting on the admin page. AJAX and Web cron will not update feeds</li> <li>Check if the cronjob exists with <code>crontab -u www-data -e</code> (replace www-data with your httpd user)</li> <li>Check the file permissions of the cron.php file and if www-data (or whatever your httpd user is called like) can read and execute that script</li> <li>Check if you can execute the cron with <code>sudo -u www-data php -f nextcloud/cron.php</code> (replace www-data with your httpd user)</li> <li>Check your <code>data/nextcloud.log</code> for errors</li> <li>Check if the cronjob is ever executed by placing an <code>error_log('updating');</code> in the background job file. If the cronjob runs, there should be an updating log statement in your httpd log.</li> <li>If there is no updating statement in your logs check if your cronjob is executed by executing a different script</li> <li>Check if the oc_jobs table has a reserved_at entry with a value other than 0. If it does for whatever reason, set it to 0. You can check this by executing:</li> </ul> <pre><code>SELECT * from oc_jobs WHERE class LIKE '%News%' ORDER BY id;\n</code></pre> <p>You will get two rows where column class will be <code>OCA\\News\\Cron\\Updater</code> and <code>OCA\\News\\Cron\\UpdaterJob</code>.</p> <p>Info</p> <p>In newer versions of News (21.x.x) the old job OCA\\News\\Cron\\Updater was removed from the DB.</p> <p>Reset the reserved_at by executing</p> <pre><code>UPDATE oc_jobs SET reserved_at = 0 WHERE id = <id from above SELECT statement>;\n</code></pre> <p>If your cron works fine, but Nextcloud's cronjobs are never executed, file a bug in server</p>"},{"location":"troubleshooting/#using-external-updater","title":"Using External Updater","text":"<ul> <li>Check if your configuration is set to not use the system cron.</li> <li>Consult the documentation of the updater</li> <li>Check your data/nextcloud.log for errors</li> </ul>"},{"location":"troubleshooting/#database-table-grows-too-big","title":"Database table grows too big","text":"<p>If your users have subscribed to some high-volume feeds where a lot of items remain unread, this can lead to an oversized news table over time. As a consequence, the database upgrade of the news app can take several hours, during which Nextcloud cannot be used.</p> <p>By default, Nextcloud News purges old news items above a certain threshold each time it fetches new news items. The maximum number of items per feed that should be kept during the purging can be defined through the \u201cMaximum read count per feed\u201d setting in the admin UI or the <code>autoPurgeCount</code> value in the config. Additionally you may enable the option to also purge unread items <code>purgeUnread</code>. This is useful if your users have large amounts of unread items. Starred items are always exempt from purging.</p> <p>The command <code>occ news:updater:after-update [--purge-unread] [<purge-count>]</code> can be used to manually purge old news items across the instance. With the <code>--purge-unread option</code>, unread items are also purged (starred items are still exempt). If <code>purge-count</code> is not specified, the configured <code>autoPurgeCount</code> is used.</p> <p>The purge count only applies to the items that are purged. For example, when purging a feed that has 100 unread items, 100 starred read items and 100 unstarred read items, using a purge-count of 50 would keep all unread and starred items and the latest 50 read items. Using a <code>purge-count</code> of 50 along with <code>--purge-unread</code> would keep the all starred items plus the latest 50 from the set of unread and read items.</p>"},{"location":"troubleshooting/#missing-4-byte-support-sqlstate22007-invalid-datetime-format-1366-incorrect-string-value","title":"Missing 4-byte support SQLSTATE[22007]: Invalid datetime format: 1366 Incorrect string value:","text":"<p>This is likely caused by your feed using emojis in the feed title or text.</p> <p>The DB is then not able to store the feed and runs into strange decoding errors.</p> <p>You need to convert your DB to support 4 bytes, check the Nextcloud documentation.</p> <p>References #1165 #526</p>"},{"location":"api/api-v1-2/","title":"External API v1-2","text":"<p>The News app 1.2 offers a RESTful API</p>"},{"location":"api/api-v1-2/#api-stability-contract","title":"API stability contract","text":"<p>The API level will change if the following occurs:</p> <ul> <li>A field of an object is removed</li> <li>A field of an object has a different datatype</li> <li>The meaning of an API call changes</li> </ul> <p>The API level will not change if:</p> <ul> <li>The app version is changed (e.g. 4.0.1.2 instead of 4.0 or 4.001)</li> <li>A new attribute is added (e.g. each item gets a new field \"something\": 1)</li> <li>The order of the JSON attributes is changed on any level (e.g. \"id\":3 is not the first field anymore, but the last)</li> </ul> <p>You have to design your app with these things in mind!:</p> <ul> <li>Don't depend on the order of object attributes. In JSON it does not matter where the object attribute is since you access the value by name, not by index</li> <li>Don't limit your app to the currently available attributes. New ones might be added. If you don't handle them, ignore them</li> <li>Use a library to compare versions, ideally one that uses semantic versioning</li> </ul>"},{"location":"api/api-v1-2/#authentication-basics","title":"Authentication & Basics","text":"<p>Because REST is stateless you have to send user and password each time you access the API. Therefore running Nextcloud with SSL is highly recommended otherwise everyone in your network can log your credentials.</p> <p>The base URL for all calls is:</p> <pre><code>https://yournextcloud.com/index.php/apps/news/api/v1-2/\n</code></pre> <p>All defined routes in the Specification are appended to this url. To access all feeds for instance use this url:</p> <pre><code>https://yournextcloud.com/index.php/apps/news/api/v1-2/feeds\n</code></pre> <p>Credentials need to be passed as an HTTP header using HTTP basic auth:</p> <pre><code>Authorization: Basic $CREDENTIALS\n</code></pre> <p>where $CREDENTIALS is:</p> <pre><code>base64(USER:PASSWORD)\n</code></pre>"},{"location":"api/api-v1-2/#how-to-sync","title":"How To Sync","text":"<p>This is a small overview over how you should sync your articles with the Nextcloud News app. For more fine-grained details about the API see further down.</p> <p>All routes are given relative to the base API url (e.g.: https://yournextcloud.com/index.php/apps/news/api/v1-2)</p>"},{"location":"api/api-v1-2/#initial-sync","title":"Initial Sync","text":"<p>The intial sync happens, when a user adds a Nextcloud account in your app. In that case you should fetch all feeds, folders and unread or starred articles from the News app. Do not fetch all articles, not only because it syncs faster, but also because the user is primarily interested in unread articles. To fetch all unread and starred articles, you must call 4 routes:</p> <ul> <li>unread articles: GET /items?type=3&getRead=false&batchSize=-1</li> <li>starred articles: GET /items?type=2&getRead=true&batchSize=-1</li> <li>folders: GET /folders</li> <li>feeds: GET /feeds</li> </ul> <p>The JSON response structures can be viewed further down.</p>"},{"location":"api/api-v1-2/#syncing","title":"Syncing","text":"<p>When syncing, you want to push read/unread and starred/unstarred items to the server and receive new and updated items, feeds and folders. To do that, call the following routes:</p> <ul> <li>Notify the News app of unread articles: PUT /items/unread/multiple {\"items\": [1, 3, 5] }</li> <li>Notify the News app of read articles: PUT /items/read/multiple {\"items\": [1, 3, 5]}</li> <li>Notify the News app of starred articles: PUT /items/starred/multiple {\"items\": [{\"feedId\": 3, \"guidHash\": \"adadafasdasd1231\"}, ...]}</li> <li>Notify the News app of unstarred articles: PUT /items/unstarred/multiple {\"items\": [{\"feedId\": 3, \"guidHash\": \"adadafasdasd1231\"}, ...]}</li> <li>Get new folders: GET /folders</li> <li>Get new feeds: GET /feeds</li> <li>Get new items and modified items: GET /items/updated?lastModified=12123123123&type=3</li> </ul>"},{"location":"api/api-v1-2/#accessing-api-from-a-web-application","title":"Accessing API from a web application","text":"<p>News 1.401 implements CORS which allows web applications to access the API. To access the API in a webapp you need to send the correct authorization header instead of simply putting auth data into the URL!. An example request in jQuery would look like this:</p> <pre><code>$.ajax({\ntype: 'GET',\nurl: 'https://yournextcloud.com/index.php/apps/news/api/v1-2/version',\ncontentType: 'application/json',\nsuccess: function (response) {\n// handle success\n},\nerror: function () {\n// handle errors\n},\nbeforeSend: function (xhr) {\nvar username = 'john';\nvar password = 'doe';\nvar auth = btoa(username + ':' + password);\nxhr.setRequestHeader('Authorization', 'Basic ' + auth);\n}\n});\n</code></pre> <p>An example with AngularJS would look like this:</p> <pre><code>angular.module('YourApp', [])\n.config(['$httpProvider', '$provide', function ($httpProvider, $provide) {\n$provide.factory('AuthInterceptor', ['Credentials', '$q', function (Credentials, $q) {\nreturn {\nrequest: function (config) {\n// only set auth headers if url matches the api url\nif(config.url.indexOf(Credentials.url) === 0) {\nauth = btoa(Credentials.userName + ':' + Credentials.password);\nconfig.headers['Authorization'] = 'Basic ' + auth;\n}\nreturn config || $q.when(config);\n}\n};\n}]);\n$httpProvider.interceptors.push('AuthInterceptor');\n}])\n.factory('Credentials', function () {\nreturn {\nuserName: 'user',\npassword: 'password',\nurl: 'https://yournextcloud.com/index.php/apps/news/api'\n};\n})\n.run(['$http', function($http) {\n$http({\nmethod: 'GET',\nurl: 'https://yournextcloud.com/index.php/apps/news/api/v1-2/version'\n}).success(function (data, status, header, config) {\n// handle success\n}).error(function (data, status, header, config) {\n// handle error\n});\n}]);\n</code></pre>"},{"location":"api/api-v1-2/#input","title":"Input","text":"<p>In general the input parameters can be in the URL or request body, the App Framework doesnt differentiate between them.</p> <p>So JSON in the request body like:</p> <pre><code>{\n\"id\": 3\n}\n</code></pre> <p>will be treated the same as</p> <pre><code>/?id=3\n</code></pre> <p>It is recommended though that you use the following convention:</p> <ul> <li>GET: parameters in the URL</li> <li>POST: parameters as JSON in the request body</li> <li>PUT: parameters as JSON in the request body</li> <li>DELETE: parameters as JSON in the request body</li> </ul>"},{"location":"api/api-v1-2/#output","title":"Output","text":"<p>The output is JSON.</p>"},{"location":"api/api-v1-2/#api-endpoints","title":"API Endpoints","text":""},{"location":"api/api-v1-2/#folders","title":"Folders","text":""},{"location":"api/api-v1-2/#get-all-folders","title":"Get all folders","text":"<ul> <li>Status: Implemented</li> <li>Method: GET</li> <li>Route: /folders</li> <li>Parameters: none</li> <li>Returns:</li> </ul> <pre><code>{\n\"folders\": [\n{\n\"id\": 4,\n\"name\": \"Media\"\n}, // etc\n]\n}\n</code></pre>"},{"location":"api/api-v1-2/#create-a-folder","title":"Create a folder","text":"<p>Creates a new folder and returns a new folder object</p> <ul> <li>Status: Implemented</li> <li>Method: POST</li> <li>Route: /folders</li> <li>Parameters:</li> </ul> <pre><code>{\n\"name\": \"folder name\"\n}\n</code></pre> <ul> <li>Return codes:</li> <li>HTTP 409: If the folder exists already</li> <li>HTTP 422: If the folder name is invalid (for instance empty)</li> <li>Returns:</li> </ul> <pre><code>{\n\"folders\": [\n{\n\"id\": 4,\n\"name\": \"Media\"\n}\n]\n}\n</code></pre>"},{"location":"api/api-v1-2/#delete-a-folder","title":"Delete a folder","text":"<p>Deletes a folder with the id folderId and all the feeds it contains</p> <ul> <li>Status: Implemented</li> <li>Method: DELETE</li> <li>Route: /folders/{folderId}</li> <li>Parameters: none</li> <li>Return codes:</li> <li>HTTP 404: If the folder does not exist</li> <li>Returns: nothing</li> </ul>"},{"location":"api/api-v1-2/#rename-a-folder","title":"Rename a folder","text":"<p>Only the name can be updated</p> <ul> <li>Status: Implemented</li> <li>Method: PUT</li> <li>Route: /folders/{folderId}</li> <li>Parameters:</li> </ul> <pre><code>{\n\"name\": \"folder name\"\n}\n</code></pre> <ul> <li>Return codes:</li> <li>HTTP 409: If the folder name does already exist</li> <li>HTTP 404: If the folder does not exist</li> <li>HTTP 422: If the folder name is invalid (for instance empty)</li> <li>Returns: nothing</li> </ul>"},{"location":"api/api-v1-2/#mark-items-of-a-folder-as-read","title":"Mark items of a folder as read","text":"<ul> <li>Status: Implemented</li> <li>Method: PUT</li> <li>Route: /folders/{folderId}/read</li> <li>Parameters:</li> </ul> <pre><code>{\n// mark all items read lower than equal that id\n// this is mean to prevent marking items as read which the client/user does not yet know of\n\"newestItemId\": 10\n}\n</code></pre> <ul> <li>Return codes:</li> <li>HTTP 404: If the feed does not exist</li> <li>Returns: nothing</li> </ul>"},{"location":"api/api-v1-2/#feeds","title":"Feeds","text":""},{"location":"api/api-v1-2/#sanitation","title":"Sanitation","text":"<p>The following attributes are not sanitized meaning: including them in your web application can lead to XSS:</p> <ul> <li>title</li> <li>link</li> </ul>"},{"location":"api/api-v1-2/#get-all-feeds","title":"Get all feeds","text":"<ul> <li>Status: Implemented</li> <li>Method: GET</li> <li>Route: /feeds</li> <li>Parameters: none</li> <li>Returns:</li> </ul> <pre><code>{\n\"feeds\": [\n{\n\"id\": 39,\n\"url\": \"http://feeds.feedburner.com/oatmealfeed\",\n\"title\": \"The Oatmeal - Comics, Quizzes, & Stories\",\n\"faviconLink\": \"http://theoatmeal.com/favicon.ico\",\n\"added\": 1367063790,\n\"folderId\": 4,\n\"unreadCount\": 9,\n\"ordering\": 0, // 0 means no special ordering, 1 means oldest first, 2 newest first, new in 5.1.0\n\"link\": \"http://theoatmeal.com/\",\n\"pinned\": true // if a feed should be sorted before other feeds, added in 6.0.3,\n\"updateErrorCount\": 0, // added in 8.6.0, 0 if no errors occured during the last update,\n// otherwise is incremented for each failed update.\n// Once it reaches a threshold, a message should be displayed to the user\n// indicating that the feed has failed to update that many times.\n// The webapp displays the message after 50 failed updates\n\"lastUpdateError\": \"error message here\" // added in 8.6.0, empty string or null if no update\n// error happened, otherwise contains the last update error message\n}, // etc\n],\n\"starredCount\": 2,\n\"newestItemId\": 3443 // only sent if there are items\n}\n</code></pre>"},{"location":"api/api-v1-2/#create-a-feed","title":"Create a feed","text":"<p>Creates a new feed and returns the feed</p> <ul> <li>Status: Implemented</li> <li>Method: POST</li> <li>Route: /feeds</li> <li>Parameters:</li> </ul> <p |