From 484878887c0ca8b056ab9453044f0f9f63bf9d68 Mon Sep 17 00:00:00 2001 From: Frederic Guillot Date: Thu, 29 Dec 2016 18:52:37 -0500 Subject: [PATCH] Update API documentation --- README.markdown | 6 +- docs/json-rpc-api.markdown | 1339 +++++++---------- jsonrpc.php | 2 +- .../integration/README.md | 1 + 4 files changed, 512 insertions(+), 836 deletions(-) rename docs/tests.markdown => tests/integration/README.md (98%) diff --git a/README.markdown b/README.markdown index cacf7b2..0cf542d 100644 --- a/README.markdown +++ b/README.markdown @@ -8,7 +8,7 @@ Miniflux is a minimalist and web-based RSS reader. Features -------- -- Host almost anywhere +- Self-hosted - Readability (CSS optimized for readability, responsive design, compatible with mobile and tablet devices) - Easy setup => **copy and paste the source code and you are done!** - Remove Feedburner Ads and analytic trackers (1x1 pixels) @@ -23,7 +23,7 @@ Features - Groups for categorization of feeds (like folders or tags) - Send your favorite articles to Pinboard, Instapaper or Wallabag - Enclosure support (videos and podcasts) -- Feed updates via a cronjob or with the user interface with one click +- Feed updates via a cronjob or with the user interface in one click - Keeps history of read items - Import/Export of OPML feeds - Themes @@ -43,6 +43,7 @@ Requirements Documentation ------------- +- [ChangeLog](https://github.com/miniflux/miniflux/blob/master/ChangeLog) - [Installation](docs/installation.markdown) - [Upgrade to a new version](docs/upgrade.markdown) - [Cronjob](docs/cronjob.markdown) @@ -54,7 +55,6 @@ Documentation - [Fever API](docs/fever.markdown) - [Run Miniflux with Docker](docs/docker.markdown) - [FAQ](docs/faq.markdown) -- [Tests](docs/tests.markdown) License ------- diff --git a/docs/json-rpc-api.markdown b/docs/json-rpc-api.markdown index 2aed889..507abad 100644 --- a/docs/json-rpc-api.markdown +++ b/docs/json-rpc-api.markdown @@ -3,7 +3,7 @@ Json-RPC API The Miniflux API is a way to interact programatically with your feeds, items, bookmarks and other data. -Developers can use this API to make a desktop or a mobile client on Android, iOS, etc... +Developers can use this API to make desktop or mobile clients. Protocol -------- @@ -20,24 +20,21 @@ Credentials ----------- The first step is to retrieve API credentials and the URL endpoint. - -Under the web user interface of Miniflux, go to the menu **preferences**, scroll down until you reach the API section. +They are available in **preferences > api**. You must have these information: -- API endpoint: `https://username.miniflux.net/jsonrpc.php` +- API endpoint: `https://your_domain.tld/jsonrpc.php` - API username: `username` -- API token: `swB3/nSo1CB1X2F` (random token) +- API token: `XXXXXX` (random token) -The API username is the same as your login username and the API token is generated automatically during the database creation. +The API username is the same as your login username and the API token is generated automatically. Authentication -------------- The API use the HTTP Basic Authentication scheme described in [RFC2617](http://www.ietf.org/rfc/rfc2617.txt). -Based on the above example, the username is "demo" and the password is the "API token" (swB3/nSo1CB1X2F). - Examples -------- @@ -45,986 +42,664 @@ Examples ```bash curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "feed.create", "params": {"url": "http://images.apple.com/main/rss/hotnews/hotnews.rss"}, "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php +-u "username:password" \ +-d '{"jsonrpc": "2.0", "method": "createFeed", "params": {"url": "http://images.apple.com/main/rss/hotnews/hotnews.rss"}, "id": 1}' \ +https://localhost/jsonrpc.php ``` -Success output: +Success response: ```json -{"jsonrpc":"2.0","id":1,"result":6} +{ + "jsonrpc": "2.0", + "id": 1, + "result": 6 +} ``` The `feed_id` is 6. -Error output: +Error response: -{"jsonrpc":"2.0","id":1,"result":false} - -### Example with PHP - -I developed a very simple [JSON-RPC client/server PHP library](https://github.com/fguillot/JsonRPC). -Here is an example to fetch all bookmarks. - -```php -use JsonRPC\Client; - -$client = new Client('https://demo.miniflux.net/jsonrpc.php'); -$client->authentication('demo', 'swB3/nSo1CB1X2F'); - -$result = $client->execute('item.bookmark.list'); -print_r($result); -``` - -Output: - -```php -Array -( - [0] => Array - ( - [id] => be1403d8 - [title] => Data Structures for PHP Devs: Heaps - [updated] => 1374503433 - [url] => http://phpmaster.com/data-structures-3/ - [status] => read - [site_url] => http://phpmaster.com - [feed_title] => PHP Master - ) - - [1] => Array - ( - [id] => 49c2f23c - [title] => Has Mozilla Lost Its Values? - [updated] => 1374171372 - [url] => https://www.iab.net/iablog/2013/07/has-mozilla-lost-its-values.html - [status] => read - [site_url] => https://lobste.rs/ - [feed_title] => lobste.rs - ) -) +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": false +} ``` Procedures ---------- -### app.version +### getVersion -Get the application version. +- Purpose: **Get application version** +- Parameters: none +- Result on success: **version** -- **Arguments:** None -- **Return:** Software version - -Request: - -```bash -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "app.version", "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: +Request example: ```json { - "jsonrpc":"2.0", - "id":1, - "result": { - "version":"master" + "jsonrpc": "2.0", + "method": "getVersion", + "id": 304873928 +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "result": "master", + "id": 304873928 +} +``` + +### createUser + +- Purpose: **Create new user** (accessible only by administrators) +- Parameters: + - **username** (string) + - **password** (string) + - **is_admin** (boolean, optional) +- Result on success: **user_id** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "createUser", + "id": 97055228, + "params": { + "username": "api_test", + "password": "test123" } } ``` -### feed.list - -Get the list of subscriptions. - -- **Arguments:** None -- **Return on success:** List of feeds -- **Return on failure:** false - -Request: - -```bash -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "feed.list", "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: +Response example: ```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : [ - { "download_content" : "0", - "enabled" : "1", - "etag" : null, - "feed_url" : "http://www.lemonde.fr/rss/une.xml", - "id" : "1", - "last_checked" : null, - "last_modified" : null, - "parsing_error" : "0", - "site_url" : "http://www.lemonde.fr/rss/une.xml", - "title" : "Le Monde.fr - Actualité à la Une", - "feed_group_ids" : [ - "1", - "2" - ] - }, - { "download_content" : "1", - "enabled" : "1", - "etag" : null, - "feed_url" : "http://www.futura-sciences.com/rss/actualites.xml", - "id" : "6", - "last_checked" : null, - "last_modified" : null, - "parsing_error" : "0", - "site_url" : "http://www.futura-sciences.com", - "title" : "Les dernières actualités de Futura-Sciences", - "feed_group_ids" : [ - "3" - ] - }, - { "download_content" : "0", - "enabled" : "1", - "etag" : null, - "feed_url" : "http://www.mac4ever.com/rss/actu", - "id" : "2", - "last_checked" : null, - "last_modified" : null, - "parsing_error" : "0", - "site_url" : "http://www.mac4ever.com/actu", - "title" : "Mac4Ever.com - Actualité", - "feed_group_ids" : [] - }, - ... - ] +{ + "jsonrpc": "2.0", + "result": 2, + "id": 97055228 } ``` -### feed.info -Fetch one subscription +### getUserByUsername -- **Arguments:** feed_id (integer) -- **Return on success:** Key-value pair -- **Return on failure:** false +- Purpose: **Get user** (accessible only by administrators) +- Parameters: + - **username** (string) +- Result on success: **user object** +- Result on failure: **false|null** -Request: +Request example: -```bash -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "feed.info", "params": {"feed_id": 1}, "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: ```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : [ - { - "download_content" : "0", - "enabled" : "1", - "etag" : null, - "feed_url" : "http://www.lemonde.fr/rss/une.xml", - "id" : "1", - "last_checked" : null, - "last_modified" : null, - "parsing_error" : "0", - "site_url" : "http://www.lemonde.fr/rss/une.xml", - "title" : "Le Monde.fr - Actualité à la Une", - "feed_group_ids" : [ - "1", - "2" - ] - } +{ + "jsonrpc": "2.0", + "method": "getUserByUsername", + "id": 1456121566, + "params": [ + "api_test" ] } ``` -### feed.create - -Add a new subscription (synchronous operation). - -- **Arguments:** url (string) -- **Return on success:** feed_id (integer) -- **Return on failure:** false - -Request: - -```bash -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "feed.create", "params": {"url": "http://images.apple.com/main/rss/hotnews/hotnews.rss"}, "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: +Response example: ```json -{"jsonrpc":"2.0","id":1,"result":6} -``` - -### feed.delete - -Remove one subscription. - -- **Arguments:** feed_id (integer) -- **Return on success:** true -- **Return on failure:** false - -Request: - -```bash -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "feed.delete", "params": {"feed_id": 5}, id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result": true -} -``` - -### feed.delete_all - -Remove all subscriptions. - -- **Arguments:** None -- **Return on success:** true -- **Return on failure:** false - -Request: - -```bash -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "feed.delete_all", "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : true -} -``` - -### feed.update - -Refresh one subscription (synchronous operation). - -- **Arguments:** feed_id (integer) -- **Return on success:** true -- **Return on failure:** false - -Request: - -```json -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "feed.update", "params": {"feed_id": 1}, id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : true -} -``` - -### group.list - -Get the list of groups. - -- **Arguments:** None -- **Return on success:** List of groups -- **Return on failure:** false - -Request: - -```bash -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "group.list", "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : [ - { "id" : "1", - "title" : "Tech" - }, - { "id" : "2", - "title" : "Hardware" - }, - { "id" : "3", - "title" : "Software" - }, - ... - ] -} -``` - -### item.feed.list - -Get all items for a specific feed. - -- **Arguments:** feed_id, offset = null, limit = null (integer) -- **Return on success:** List of items -- **Return on failure:** false - -Request: - -```json -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "item.feed.list", "params": {"feed_id": 1}, id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : [ - { - "bookmark" : "0", - "content" : "<p>La fermeture de quatre usines affecte 1 250 salariés, soit 30 % des effectifs de la marque en Espagne.</p>", - "feed_id" : "1", - "id" : "bcc94722", - "site_url" : "http://www.lemonde.fr/rss/une.xml", - "status" : "unread", - "title" : "Des milliers de manifestants à Madrid contre la fermeture d'usines Coca-Cola", - "updated" : "1392486765", - "url" : "http://www.lemonde.fr/europe/article/2014/02/15/des-milliers-de-manifestants-a-madrid-contre-la-fermeture-d-usines-coca-cola_4367428_3214.html#xtor=RSS-3208" +{ + "jsonrpc": "2.0", + "result": { + "id": "2", + "username": "api_test", + "password": "$2y$10$FOzlRrLoHRI3Xj4YuV8z5O1jI4CKda61reX.g.Fm4ctYMijpOhTGu", + "is_admin": "0", + "last_login": null, + "api_token": "398c293808aaed9cf2be45cf8e4fa303be5cdbbf6c4a55fece6b585c6a6c", + "bookmarklet_token": "965e9049138e4e78c398dc369fc4ec529226055c6fd77a3d4119bc3a1b5e", + "cronjob_token": "a4f6e1f5fd655c7365ebddcaf1dfd5782669186ed85a788d8e52b8230399", + "feed_token": "62ed60fb75616d3f81a938206449a20fe30f0bf9db9bf0b93259821f5938", + "fever_token": "59253f797b3b1885e31449fa97e9348c127e4e10e4eea959a2555c1b3a1e", + "fever_api_key": "5e379736d05847f87c37a7d2f57ed234" }, - { - "bookmark" : "0", - "content" : "<p>Le Français a passé samedi la barre des 6,16 mètres, dépassant ainsi le saut de l'Ukrainien à 6,15 mètres atteint en 1993.</p>", - "feed_id" : "1", - "id" : "c659783b", - "site_url" : "http://www.lemonde.fr/rss/une.xml", - "status" : "unread", - "title" : "Saut à la perche : Lavillenie bat le record du monde de Bubka", - "updated" : "1392486633", - "url" : "http://www.lemonde.fr/sport/article/2014/02/15/saut-a-la-perche-lavillenie-bat-le-record-du-monde-de-bubka_4367434_3242.html#xtor=RSS-3208" + "id": 1456121566 +} +``` + + +### getFeeds + +- Purpose: **Get all subscriptions** +- Parameters: none +- Result on success: **list of feed objects** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "getFeeds", + "id": 1189414818 +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "result": [ + { + "id": "1", + "user_id": "1", + "feed_url": "https:\/\/miniflux.net\/feed", + "site_url": "https:\/\/miniflux.net\/", + "title": "Miniflux", + "last_checked": "1483053994", + "last_modified": "Sun, 31 Jul 2016 16:54:32 GMT", + "etag": "W\/\"bdc7a83fd61620b778da350991501757\"", + "enabled": "1", + "download_content": "0", + "parsing_error": "0", + "rtl": "0", + "cloak_referrer": "0", + "parsing_error_message": null, + "expiration": "1483226794", + "groups": [ + { + "id": "1", + "title": "open source software" + } + ] + } + ], + "id": 1189414818 +} +``` + +### getFeed + +- Purpose: **Get one subscription** +- Parameters: + - **feed_id** (integer) +- Result on success: **feed object** +- Result on failure: **null** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "getFeed", + "id": 912101777, + "params": [ + 1 + ] +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "result": { + "id": "1", + "user_id": "1", + "feed_url": "https:\/\/miniflux.net\/feed", + "site_url": "https:\/\/miniflux.net\/", + "title": "Miniflux", + "last_checked": "1483053994", + "last_modified": "Sun, 31 Jul 2016 16:54:32 GMT", + "etag": "W\/\"bdc7a83fd61620b778da350991501757\"", + "enabled": "1", + "download_content": "0", + "parsing_error": "0", + "rtl": "0", + "cloak_referrer": "0", + "parsing_error_message": null, + "expiration": "1483226794", + "groups": [ + { + "id": "1", + "title": "open source software" + } + ] }, - ... + "id": 912101777 +} +``` + +### createFeed + +- Purpose: **Add new subscription** +- Parameters: + - **url** (string) + - **download_content** (boolean, optional) + - **rtl** (boolean, optional) + - **group_name** (string, optional) +- Result on success: **feed_id** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "createFeed", + "id": 315813488, + "params": { + "url": "https://miniflux.net/feed", + "group_name": "open source software" + } +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "result": 1, + "id": 315813488 +} +``` + +### removeFeed + +- Purpose: **Create new user** +- Parameters: + - **feed_id** (integer) +- Result on success: **true** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "removeFeed", + "id": 1793804609, + "params": [ + 1 ] } ``` -### item.feed.count - -Count all items for a specific feed. - -- **Arguments:** feed_id (integer) -- **Return on success:** Number of items (integer) -- **Return on failure:** false - -Request: - -```bash -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "item.feed.count", "params": {"feed_id": 1}, "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: +Response example: ```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : 25 +{ + "jsonrpc": "2.0", + "result": true, + "id": 1793804609 } ``` -### item.bookmark.list +### refreshFeed -Get all bookmarks. +- Purpose: **Refresh subscription** (synchronous call) +- Parameters: + - **feed_id** (integer) +- Result on success: **true** +- Result on failure: **false** -- **Arguments:** offset = null, limit = null (integer) -- **Return on success:** List of items -- **Return on failure:** false - -Request: +Request example: ```json -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "item.bookmark.list", "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : [ - { - "bookmark" : "1", - "content" : "La fermeture de quatre usines affecte 1 250 salariés, soit 30 % des effectifs de la marque en Espagne.", - "feed_id" : "1", - "feed_title" : "Le Monde.fr - Actualité à la Une", - "id" : "bcc94722", - "site_url" : "http://www.lemonde.fr/rss/une.xml", - "status" : "unread", - "title" : "Des milliers de manifestants à Madrid contre la fermeture d'usines Coca-Cola", - "updated" : "1392486765", - "url" : "http://www.lemonde.fr/europe/article/2014/02/15/des-milliers-de-manifestants-a-madrid-contre-la-fermeture-d-usines-coca-cola_4367428_3214.html#xtor=RSS-3208" - }, - ... +{ + "jsonrpc": "2.0", + "method": "refreshFeed", + "id": 181234449, + "params": [ + 1 ] } ``` -### item.bookmark.count - -Count the number of bookmarks. - -- **Arguments:** Nothing -- **Return on success:** Number of items (integer) -- **Return on failure:** false - -Request: +Response example: ```json -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "item.bookmark.count", "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : 3 +{ + "jsonrpc": "2.0", + "result": true, + "id": 181234449 } ``` -### item.bookmark.create +### getItems -Add a new bookmark. +- Purpose: **Get list o items** +- Parameters: + - **since_id** (integer, optional) Returns only feeds from this item id + - **item_ids** ([]integer, optional) Returns only items in this list + - **limit** (integer, optional, default=50) Change number of items returned +- Result on success: **list of item objects** +- Result on failure: **false** -- **Arguments:** item_id -- **Return on success:** true -- **Return on failure:** false - -Request: +Request example: ```json -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "item.bookmark.create", "params": {"item_id": "1fd17ad3"}, "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : true +{ + "jsonrpc": "2.0", + "method": "getItems", + "id": 84429548, + "params": { + "since_id": 2 + } } ``` -### item.bookmark.delete - -Remove a bookmark. - -- **Arguments:** item_id -- **Return on success:** 1 (integer) -- **Return on failure:** false - -Request: +Response example: ```json -curl \ --u "demo:swB3/nSo1CB1X2F" \ --d '{"jsonrpc": "2.0", "method": "item.bookmark.delete", "params": {"item_id": "1fd17ad3"}, "id": 1}' \ -https://demo.miniflux.net/jsonrpc.php -``` - -Response: - -```json -{ "id" : 1, - "jsonrpc" : "2.0", - "result" : true +{ + "jsonrpc": "2.0", + "result": [ + { + "id": "3", + "checksum": "7f4b791f", + "title": "Miniflux 1.1.8 released", + "updated": "1442016000", + "url": "https:\/\/miniflux.net\/news\/version-1.1.8", + "enclosure_url": "", + "enclosure_type": "", + "bookmark": "0", + "feed_id": "1", + "status": "unread", + "content": "