FreshRSS/docs/en/developers/06_Fever_API.md

FreshRSS - Fever API implementation

See Mobile access for general aspects of API access. Additionally page about our Google Reader compatible API for another possibility.

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, 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

App	Platform	License
Fluent Reader	Windows, Linux, macOS	BSD-3-Clause
Fluent Reader lite	Android, iOS	BSD-3-Clause
Read You	Android	GPLv3
Fiery Feeds	iOS	Closed Source
Newsflash	Linux	GPLv3
Unread	iOS	Closed Source
Reeder Classic	iOS	Closed Source
ReadKit	macOS	Closed Source
FreshRSS Python API Client	Python	GPLv3

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.

Configure a POST request to the URL https://freshrss.example.net/api/fever.php?api which should give you the result:

{
	"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

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:

curl -s -F "api_key=$api_key" 'https://freshrss.example.net/api/fever.php?api'

This should give:

{
	"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 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:

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.