FreshAPI
A FreshRSS / Google Reader API Plugin for Tiny-Tiny RSS
Background
Tiny-Tiny RSS is one of the best and most customizable self-hostable RSS readers available, but has limited compatibility with third party RSS readers through two APIs:
Many mobile applications support one of these protocols, many do not. FreshAPI implements the FreshRSS / Google Reader API to allow Tiny-Tiny RSS to be used with more third party apps, and with more features.
| Feature | Fever API | Official API | FreshAPI |
|---|---|---|---|
| Mark Article as Read/Unread | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Add/Remove Star from Article | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Mark Entire Feed/Category as Read | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Secure Implementation | :x: | :white_check_mark: | :white_check_mark: |
| Subscribe to a Feed | :x: | :white_check_mark: | :white_check_mark: |
| Unsubscribe from a Feed | :x: | :white_check_mark: | :white_check_mark: |
| Rename a Feed | :x: | :x: | :white_check_mark: |
| Add a Category to a Feed | :x: | :x: | :white_check_mark: |
| Remove a Category from a Feed | :x: | :x: | :white_check_mark: |
| Create a new Category | :x: | :x: | :white_check_mark: |
| Rename a Label | :x: | :x: | :white_check_mark: |
| Delete a Label | :x: | :x: | :white_check_mark: |
| OPML Export | :x: | :x: | :white_check_mark: |
| OPML Import | :x: | :x: | :white_check_mark: |
Requirements
FreshAPI assumes that you're using the official docker based integration and running the latest version of TT-RSS. A change required for the API to work (enabling PATH_INFO for the plugins.local directory) was pushed on 9/11/2024, so any docker images from before that change will need to be updated.
If you are using another installation method please provide details about your setup in any issues you open.
Installation
-
Clone this repository into your Tiny Tiny RSS plugins directory:
cd tt-rss/plugins.local git clone https://github.com/eric-pierce/freshapi.git -
Navigate to the Preferences menu in Tiny Tiny RSS, and check the box under "General" titled "Enable API"
-
In Preferences, open the Plugin menu and enable "freshapi"
-
When configuring your mobile app, select either "FreshRSS" or "Google Reader API". You'll need to point your client to your TT-RSS installation, depending on your setup. If you're using a subdomain to host TT-RSS then use
https://yoursubdomain.yourdomain.cominstead ofhttps://yourdomain.comin the requests below.If you're using the standard docker installation use
https://yourdomain.com/tt-rss/plugins.local/freshapi/api/greader.phpas the server URL.If you're running the TT-RSS app at the website root (not including /tt-rss/ in the URL) by using the APP_WEB_ROOT and APP_BASE environment variables as described here you'll also need to remove tt-rss from the domain you use with clients:
https://yourdomain.com/plugins.local/freshapi/api/greader.phpUse your standard TT-RSS username and password. If you've enabled 2 Factor Authentication (2FA) generate and use an App Password.
Compatible Clients
The following clients have been tested, but FreshAPI should be compatible with any FreshRSS or Google Reader API compatible client. If you run into any issues or would like to report a client as working, please open up an issue.
| App | Platform | Status | Notes |
|---|---|---|---|
| Reeder Classic | iOS, macOS | Fully Functional | None |
| NetNewsWire | iOS, macOS | Fully Functional | None |
| lire | iOS, macOS | Fully Functional | None |
| Fiery Feeds | iOS, macOS | Fully Functional | None |
| ReadKit | iOS, macOS | Fully Functional | None |
| Fluent Reader | iOS, macOS | Fully Functional | None |
| FeedMe | Android | Fully Functional | None |
| Read You | Android | Fully Functional | None |
Using the API
FreshRSS and Google Reader compatible clients can natively use this API, but if you'd like to access it directly you can do so by making cURL calls. The Google Reader API spec is well documented, but here is an example of API usage:
- Authorization
Make a POST cURL call to your server's ClientLogin Endpoint using your TT-RSS username and password. If you have enabled 2FA you can use an App password generated in the TT-RSS preferences pane
foo@bar:~$ curl -X POST --data 'Email=yourusername&Passwd=yourpassword' https://example.com/tt-rss/plugins.local/freshapi/api/greader.php/accounts/ClientLogin/This will return your authorization credentials in the format 'username/session_id"
SID=yourusername/r4ih6gt412opqh11gptp3hodd6
LSID=
Auth=yourusername/r4ih6gt412opqh11gptp3hodd6- Calling the API Directly
Take the username/session_id combination from step 1 and make a new cURL call to the endpoint you'd like to use. In this case we'll ask to export the subscription, folder, and tag OPML through the subscription export feature:
foo@bar:~$ curl -X POST --header 'Authorization: GoogleLogin auth=yourusername/r4ih6gt412opqh11gptp3hodd6' https://example.com/tt-rss/plugins.local/freshapi/api/greader.php/reader/api/0/subscription/exportIn the example above the cURL call will return your subscription OPML in XML form.
Updates
FreshAPI uses a rolling release approach, though I'll increment the version number for significant changes. If cloned into the plugins.local folder TT-RSS should keep the plugin up to date.
Issues & Contributing
Both Issues and Contributions and Pull Requests are welcome and encouraged - please feel free to open either.
License
This project is licensed under the GNU AGPL 3 License
Acknowledgements
- Major thanks to Tiny Tiny RSS and its developer Andrew for making the best self-hosted RSS reader available
- Thanks to the FreshRSS team for both expanding on the Google Reader API and for providing an excellent example of implementation using PHP found here
Disclaimer
This project is not affiliated with or endorsed by FreshRSS, Google, or Tiny Tiny RSS. Use at your own risk.