From 8f1bad60d0b7bd0d0a05bcdcf3c6834e39c0c6eb Mon Sep 17 00:00:00 2001 From: Kevin Papst Date: Thu, 24 May 2018 21:53:47 +0200 Subject: Add Fever API and user documentation (#1836) * added fever api and documentation * spaces to tabs * fixed code format * added links * added utf8 to header * removed XML support * removed before check, as we have to convert it afterwards * added sandboxed setting (currently disabled) added support for extensions using entry_before_display * listFeedsOrderUpdate LIMIT https://github.com/FreshRSS/FreshRSS/pull/1836/files#r175287881 * removed custom sql by using FreshRSS_FeedDAO::listFeedsOrderUpdate() * fixed mark all as read * replaced custom sql for getUnread() and getStarred() with dao functions * removed sanitization functions * Rework fever login * Fix config bug Plus documentation * Fix array syntax For compatibility with PHP 5.3 * Disable cookies and session for API * Fix currentUser * added response header and error log * adjusted phpdoc to match new authentication * Mechanism to delete old keys * replace PHP_INT_MAX with zero to disable limit * replace method_exists with check for explicit methods * removed Press support and smaller refactoring + updated docu * Rewrite bindParamArray Avoid one of the SQL injection risks * Docs and readme * Fix API link * Simplify reverse key check Using userConfig --- docs/en/users/06_Fever_API.md | 110 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 docs/en/users/06_Fever_API.md (limited to 'docs/en/users/06_Fever_API.md') diff --git a/docs/en/users/06_Fever_API.md b/docs/en/users/06_Fever_API.md new file mode 100644 index 000000000..58e986a64 --- /dev/null +++ b/docs/en/users/06_Fever_API.md @@ -0,0 +1,110 @@ +# FreshRSS - Fever API implementation + +## RSS clients + +There are many RSS clients existing supporting Fever APIs but they seem to understand the Fever API a bit differently. +If your favourite client does not work properly with this API, create an issue and we will have a look. +But we can **only** do that for free clients. + +### Usage & Authentication + +Before you can start to use this API, you have to enable and setup API access, which is [documented here](https://freshrss.github.io/FreshRSS/en/users/06_Mobile_access.html), +and then re-set the user’s API password. + +Then point your mobile application to the URL of `fever.php` (e.g. `https://freshrss.example.net/api/fever.php`). + +## Compatibility + +Tested with: + +- iOS + - [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303) + - [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153) + +- MacOS + - [Readkit](https://itunes.apple.com/app/readkit/id588726889) + +- Android + -Until now, we don't know about compatible Android clients. Please leave your feedback, if you tested the Fever API with Android apps. + - Please note, that *Press* is NOT compatible: it was a popular RSS client with Fever support, but its development stopped a while ago. It uses the Fever API in a wrong way, which we don't support. + +## Features + +Following features are implemented: + +- fetching categories +- fetching feeds +- fetching RSS items (new, favorites, unread, by_id, by_feed, by_category, since) +- fetching favicons +- setting read marker for item(s) +- setting starred marker for item(s) +- setting read marker for feed +- setting read marker for category +- supports FreshRSS extensions, which use th `entry_before_display` hook + +Following features are not supported: +- **Hot Links** aka **hot** as there is nothing in FreshRSS yet that is similar or could be used to simulate it + +## Testing and error search + +If this API does not work as expected in your RSS reader, you can test it manually with a tool like [Postman](https://www.getpostman.com/). + +Configure a POST request to the URL https://freshrss.example.net/api/fever.php?api which should give you the result: +```json +{ + "api_version": 3, + "auth": 0 +} +``` +Great, the base setup seems to work! + +Now lets try an authenticated call. Fever uses an `api_key`, which is the MD5 hash of `"$username:$apiPassword"`. +Assuming the user is `kevin` and the password `freshrss`, here is a command-line example to compute the resulting `api_key` + +```sh +api_key=`echo -n "kevin:freshrss" | md5sum | cut -d' ' -f1` +``` + +Add a body to your POST request encoded as `form-data` and one key named `api_key` with the value `your-password-hash`: + +```sh +curl -s -F "api_key=$api_key" 'https://freshrss.example.net/api/fever.php?api' +``` + +This shoud give: +```json +{ + "api_version": 3, + "auth": 1, + "last_refreshed_on_time": "1520013061" +} +``` +Perfect, you are authenticated and can now start testing the more advanced features. Therefor change the URL and append the possible API actions to your request parameters. Check the [original Fever documentation](https://feedafever.com/api) for more infos. + +Some basic calls are: + +- https://freshrss.example.net/api/fever.php?api&items +- https://freshrss.example.net/api/fever.php?api&feeds +- https://freshrss.example.net/api/fever.php?api&groups +- https://freshrss.example.net/api/fever.php?api&unread_item_ids +- https://freshrss.example.net/api/fever.php?api&saved_item_ids +- https://freshrss.example.net/api/fever.php?api&items&since_id=some_id +- https://freshrss.example.net/api/fever.php?api&items&max_id=some_id +- https://freshrss.example.net/api/fever.php?api&mark=item&as=read&id=some_id +- https://freshrss.example.net/api/fever.php?api&mark=item&as=unread&id=some_id + +Replace `some_id` with a real ID from your `freshrss_username_entry` database. + +### Debugging + +If nothing helps and your clients still misbehaves, add these lines to the start of `fever.api`: + +```php +file_put_contents(__DIR__ . '/fever.log', $_SERVER['HTTP_USER_AGENT'] . ': ' . json_encode($_REQUEST) . PHP_EOL, FILE_APPEND); +``` + +Then use your RSS client to query the API and afterwards check the file `fever.log`. + +## Credits + +This plugin was inspired by the [tinytinyrss-fever-plugin](https://github.com/dasmurphy/tinytinyrss-fever-plugin). -- cgit v1.2.3 From 4b9f0710ebad4b07da1d5e95eced5771bf576847 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 3 Jun 2018 13:14:42 +0200 Subject: A bit of API documentation (#1914) https://github.com/FreshRSS/FreshRSS/issues/1754 --- CHANGELOG.md | 2 +- README.fr.md | 6 +++--- README.md | 6 +++--- docs/en/users/06_Fever_API.md | 3 +++ docs/en/users/06_Mobile_access.md | 34 ++++++++++++++++++++++++++++++++++ docs/fr/users/06_Fever_API.md | 2 ++ docs/fr/users/06_Mobile_access.md | 36 +++++++++++++++++++++++++++++++++++- 7 files changed, 81 insertions(+), 8 deletions(-) (limited to 'docs/en/users/06_Fever_API.md') diff --git a/CHANGELOG.md b/CHANGELOG.md index 933c831c6..39bf723d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,7 +25,7 @@ * Fix Docker bug affecting Apache `CustomLog` (unwanted local copy of access logs), `ErrorLog`, `Listen` (IPv6 bug) [#1873](https://github.com/FreshRSS/FreshRSS/pull/1873) * Fix muted feeds that were not actually muted [#1844](https://github.com/FreshRSS/FreshRSS/issues/1844) * Fix null exception in shares, showing only the first article [#1824](https://github.com/FreshRSS/FreshRSS/issues/1824) - * Fix error during import[#1890](https://github.com/FreshRSS/FreshRSS/issues/1890) + * Fix error during import [#1890](https://github.com/FreshRSS/FreshRSS/issues/1890) * Fix additional automatic sequence bug with PostgreSQL [#1907](https://github.com/FreshRSS/FreshRSS/pull/1907) * Fix errors in case of empty/wrong username when updating user settings [#1857](https://github.com/FreshRSS/FreshRSS/pull/1857) * Fixes in subscription menu [#1858](https://github.com/FreshRSS/FreshRSS/pull/1858) diff --git a/README.fr.md b/README.fr.md index 2cdab269b..78a182d7b 100644 --- a/README.fr.md +++ b/README.fr.md @@ -186,10 +186,10 @@ Voir notre [documentation sur l’API Fever](https://freshrss.github.io/FreshRSS Tout client supportant une API de type Fever ; Sélection : * iOS - * [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303) - * [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153) + * [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303) (Propriétaire) + * [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153) (Propriétaire) * MacOS - * [Readkit](https://itunes.apple.com/app/readkit/id588726889) + * [Readkit](https://itunes.apple.com/app/readkit/id588726889) (Propriétaire) # Bibliothèques incluses diff --git a/README.md b/README.md index 75136e5e7..7d6c51338 100644 --- a/README.md +++ b/README.md @@ -186,10 +186,10 @@ See our [Fever API documentation](https://freshrss.github.io/FreshRSS/en/users/0 Supported clients are: * iOS - * [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303) - * [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153) + * [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303) (Closed source) + * [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153) (Closed source) * MacOS - * [Readkit](https://itunes.apple.com/app/readkit/id588726889) + * [Readkit](https://itunes.apple.com/app/readkit/id588726889) (Closed source) # Included libraries diff --git a/docs/en/users/06_Fever_API.md b/docs/en/users/06_Fever_API.md index 58e986a64..6d8a103b9 100644 --- a/docs/en/users/06_Fever_API.md +++ b/docs/en/users/06_Fever_API.md @@ -1,5 +1,8 @@ # FreshRSS - Fever API implementation +See the [page about our Google Reader compatible API](06_Mobile_access.md) for another possibility +and general aspects of API access. + ## RSS clients There are many RSS clients existing supporting Fever APIs but they seem to understand the Fever API a bit differently. diff --git a/docs/en/users/06_Mobile_access.md b/docs/en/users/06_Mobile_access.md index 166985585..c354f98f0 100644 --- a/docs/en/users/06_Mobile_access.md +++ b/docs/en/users/06_Mobile_access.md @@ -7,6 +7,9 @@ This page assumes you have completed the [server setup](../admins/02_Installatio * Every user must define an API password. * The reason for an API-specific password is that it may be used in less safe situations than the main password, and does not grant access to as many things. +The rest of this page is about the Google Reader compatible API. +See the [page about the Fever compatible API](06_Fever_API.md) for another possibility. + # Testing @@ -50,3 +53,34 @@ This page assumes you have completed the [server setup](../admins/02_Installatio * [EasyRSS](https://github.com/Alkarex/EasyRSS) (Open source, [F-Droid](https://f-droid.org/packages/org.freshrss.easyrss/)) * Linux * [FeedReader 2.0+](https://jangernert.github.io/FeedReader/) (Open source) + + +# Google Reader compatible API + +Examples of basic queries: + +```sh +# Initial login, using API password (Email and Passwd can be given either as GET, or POST - better) +curl 'https://freshrss.example.net/api/greader.php/accounts/ClientLogin?Email=alice&Passwd=Abcdef123456' +SID=alice/8e6845e089457af25303abc6f53356eb60bdb5f8 +Auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8 + +# Examples of read-only requests +curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list?output=json' + +curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count?output=json' + +curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list?output=json' + +# Retrieve a token for requests making modifications +curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/token' +8e6845e089457af25303abc6f53356eb60bdb5f8ZZZZZZZZZZZZZZZZZ + +# Get articles, piped to jq for easier JSON reading +curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/reading-list' | jq . +``` diff --git a/docs/fr/users/06_Fever_API.md b/docs/fr/users/06_Fever_API.md index f9dcd5d73..6ad817041 100644 --- a/docs/fr/users/06_Fever_API.md +++ b/docs/fr/users/06_Fever_API.md @@ -1,5 +1,7 @@ # FreshRSS - API compatible Fever +Voir la page [sur notre API compatible Google Reader](06_Mobile_access.md) pour une autre possibilité +et des généralités sur l’accès par API. ## Compatibilité diff --git a/docs/fr/users/06_Mobile_access.md b/docs/fr/users/06_Mobile_access.md index 8ef3d038a..b8e7c31f0 100644 --- a/docs/fr/users/06_Mobile_access.md +++ b/docs/fr/users/06_Mobile_access.md @@ -7,6 +7,9 @@ Cette page suppose que vous avez fini [l’installation du serveur](01_Installat * Chaque utilisateur doit choisir son mot de passe API. * La raison d’être d’un mot de passe API différent du mot de passe principal est que le mot de passe API est potentiellement utilisé de manière moins sûre, mais il permet aussi moins de choses. +Le reste de cette page concerne l’API compatible Google Reader. +Voir la [page sur l’API compatible Fever](06_Fever_API.md) pour une autre possibilité. + # Tester @@ -17,7 +20,7 @@ Cette page suppose que vous avez fini [l’installation du serveur](01_Installat * Si vous obtenez un autre message d’erreur, passer à l’étape 5. -# Débogger la configuration du serveur +# Déboguer la configuration du serveur 5. Cliquer sur le second lien “Check partial server configuration (without `%2F` support)”: * Si vous obtenez `PASS`, alors le problème est bien que votre serveur n’accepte pas les slashs `/` qui sont encodés `%2F`. @@ -48,3 +51,34 @@ Tout client supportant une API de type Google Reader. Sélection : * [EasyRSS](https://github.com/Alkarex/EasyRSS) (Libre, F-Droid) * Linux * [FeedReader 2.0+](https://jangernert.github.io/FeedReader/) (Libre) + + +# API compatible Google Reader + +Exemples de requêtes simples: + +```sh +# Authentification utilisant le mot de passe API (Email et Passwd peuvent être passés en GET, ou POST - mieux) +curl 'https://freshrss.example.net/api/greader.php/accounts/ClientLogin?Email=alice&Passwd=Abcdef123456' +SID=alice/8e6845e089457af25303abc6f53356eb60bdb5f8 +Auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8 + +# Exemples de requêtes en lecture +curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list?output=json' + +curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count?output=json' + +curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list?output=json' + +# Demande de jeton pour faire de requêtes de modification +curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/token' +8e6845e089457af25303abc6f53356eb60bdb5f8ZZZZZZZZZZZZZZZZZ + +# Récupère les articles, envoyés à jq pour une lecture JSON plus facile +curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \ + 'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/reading-list' | jq . +``` -- cgit v1.2.3