mirror of
https://github.com/FreshRSS/FreshRSS.git
synced 2026-10-21 10:44:34 -04:00
Frans de Jonge
705318aa39
* [i18n] Add docs po4a script * Add proof of concept * Add a few more translations * Hush ShellCheck and shfmt * Make that list po4a-friendly * drat, this document could've probably been auto-generated * Definitive proof that it's translated from French ;-) * Add some brand spanking new French translation * More translation * Mostly finish that config page * Fix up FAQ * More contributing * Dev first steps * Let's ignore that admin stuff at the very least for now * Translate release new version, make French the source first and copy all translations Then replace French with English in the source. Much quicker than any alternative route. * And add the English translation * Minor stylistic leftover from French * Most of first steps * Forgot the extensions * Use po4a 0.56 to get rid of way too many newlines * Fix up those newlines * No point linking to Firefox integration anymore from the new user guide * Start on main view * A bunch of main view stuff * More main view * And some subscriptions before going to bed * First steps for devs * More dev first steps * Incomplete French → English dev/GH translation Because I need to ask about that mailing list thing * Fix typo in docs/en/developers/02_Github.md * Translate & complete devs/github to English * Fix up most of extensions * Is that supposed to be a non-breaking space? Let's see * Match up some users/mobile access * More users/mobile access * Add fresh French translation to Fever API * Fix typo * Match frontend todo thingies * Fix a typo * Some extensions strings * Remove Fx subscription service from the docs Cf. https://github.com/FreshRSS/FreshRSS/pull/2606 * Add translation for https://github.com/FreshRSS/FreshRSS/pull/2643 * fix typo as per https://github.com/FreshRSS/FreshRSS/pull/2643#discussion_r345433009 * Add some more French translations * Update French translation as per @aledeg comment https://github.com/FreshRSS/FreshRSS/pull/2590#discussion_r345465909 * Translate some of the meaningless stuff * Translate the rest of contributing.md to French * Fix conflicts * Translate Docker first steps to French * Update with change from #2665 * Add @aledeg corrections * Overlooked a couple @aledeg corrections thanks to GitHub autohide * Latest @aledeg suggestions
116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
# 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 that support the Fever API, but they seem to understand the Fever API a bit differently.
|
||
If your favourite client doesn't work properly with this API, please create an issue and we'll have a look.
|
||
But we can **only** do that for free clients.
|
||
|
||
### Usage & Authentication
|
||
|
||
Before you can start using 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 reset the user’s API password.
|
||
|
||
Then point your mobile application to the `fever.php` address (e.g. `https://freshrss.example.net/api/fever.php`).
|
||
|
||
## Compatible clients
|
||
|
||
Tested with:
|
||
|
||
* Android
|
||
* [Readably](https://play.google.com/store/apps/details?id=com.isaiasmatewos.readably) (Closed source)
|
||
|
||
* iOS
|
||
* [Fiery Feeds](https://apps.apple.com/app/fiery-feeds-rss-reader/id1158763303) (Closed source)
|
||
* [Unread](https://apps.apple.com/app/unread-rss-reader/id1252376153) (Commercial)
|
||
* [Reeder](https://www.reederapp.com/) (Commercial) (Use its Google Reader API / native FreshRSS option when possible)
|
||
|
||
* MacOS
|
||
* [ReadKit](https://apps.apple.com/app/readkit/id588726889) (Commercial)
|
||
|
||
|
||
## Features
|
||
|
||
The 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 the `entry_before_display` hook
|
||
|
||
The 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 debugging
|
||
|
||
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 should give:
|
||
```json
|
||
{
|
||
"api_version": 3,
|
||
"auth": 1,
|
||
"last_refreshed_on_time": "1520013061"
|
||
}
|
||
```
|
||
Perfect, you're now authenticated and you can start testing the more advanced features. To do so, change the URL and append the possible API actions to your request parameters. Please refer to the [original Fever documentation](https://feedafever.com/api) for more information.
|
||
|
||
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 client is still misbehaving, you can add the following lines to the beginning of the `fever.api` file to determine the cause of the problems:
|
||
|
||
```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).
|