jan/miniflux-legacy
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
7ea37a1790
miniflux-legacy/docs/json-rpc-api.markdown

982 lines
21 KiB
Markdown
Raw Normal View History

Add Json-RPC API documentation
2014-10-31 02:56:29 +01:00
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...
Protocol
--------
The API use the [JSON-RPC](http://www.jsonrpc.org/) protocol because it's very simple.
JSON-RPC is a remote procedure call protocol encoded in JSON.
Almost the same thing as XML-RPC but with JSON.
We use the [version 2](http://www.jsonrpc.org/specification) of the protocol.
You must call the API with a **POST** HTTP request.
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.
You must have these information:
- API endpoint: `https://miniflux.net/[username]/jsonrpc.php`
- API username: `username`
- API token: `swB3/nSo1CB1X2F` (random token)
The API username is the same as your login username and the API token is generated automatically during the database creation.
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
--------
### Example with cURL
```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://miniflux.net/demo/jsonrpc.php
```
Success output:
```json
{"jsonrpc":"2.0","id":1,"result":6}
```
The `feed_id` is 6.
Error output:
{"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://miniflux.net/demo/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
)
)
```
Procedures
----------
Add software version to the api
2015-04-18 17:42:10 +02:00
### app.version
Get the application version.
- **Arguments:** None
- **Return:** Software version
Request:
```bash
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "app.version", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{
"jsonrpc":"2.0",
"id":1,
"result": {
"version":"master"
}
}
```
Add Json-RPC API documentation
2014-10-31 02:56:29 +01:00
### 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://miniflux.net/demo/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"
},
{ "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"
},
{ "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.info
Fetch one subscription
- **Arguments:** feed_id (integer)
- **Return on success:** Key-value pair
- **Return on failure:** false
Request:
```bash
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "feed.info", "params": {"feed_id": 1}, "id": 1}' \
https://miniflux.net/demo/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.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://miniflux.net/demo/jsonrpc.php
```
Response:
```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://miniflux.net/demo/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://miniflux.net/demo/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://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### 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://miniflux.net/demo/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"
},
{
"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"
},
...
]
}
```
### 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://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : 25
}
```
### item.bookmark.list
Get all bookmarks.
- **Arguments:** 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.bookmark.list", "id": 1}' \
https://miniflux.net/demo/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"
},
...
]
}
```
### item.bookmark.count
Count the number of bookmarks.
- **Arguments:** Nothing
- **Return on success:** Number of items (integer)
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.bookmark.count", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : 3
}
```
### item.bookmark.create
Add a new bookmark.
- **Arguments:** item_id
- **Return on success:** true
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.bookmark.create", "params": {"item_id": "1fd17ad3"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### item.bookmark.delete
Remove a bookmark.
- **Arguments:** item_id
- **Return on success:** 1 (integer)
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.bookmark.delete", "params": {"item_id": "1fd17ad3"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### item.list_unread
Get all unread items.
- **Arguments:** 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.list_unread", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : [
{
"bookmark" : "0",
"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"
},
...
]
}
```
### item.count_unread
Count all unread items.
- **Arguments:** Nothing
- **Return on success:** Number of items (integer)
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.count_unread", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : 18
}
```
### item.list_read
Get all read items.
- **Arguments:** 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.list_read", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" :
{
"bookmark" : "0",
"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" : "read",
"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"
},
...
}
```
### item.count_read
Count all read items.
- **Arguments:** Nothing
- **Return on success:** Number of items (integer)
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.count_read", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : 254
}
```
### item.info
Fetch one item.
- **Arguments:** item_id
- **Return on success:** Key-value pair
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.info", "params": {"item_id": "bcc94722"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : {
"author" : "",
"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",
"id" : "bcc94722",
"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"
}
}
```
### item.delete
Remove one item.
- **Arguments:** item_id
- **Return on success:** true
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.delete", "params": {"item_id": "bcc94722"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### item.mark_as_read
Mark an item as read.
- **Arguments:** item_id
- **Return on success:** true
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.mark_as_read", "params": {"item_id": "1fd17ad3"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### item.mark_as_unread
Mark an item as unread.
- **Arguments:** item_id
- **Return on success:** true
- **Return on failure: **false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.mark_as_read", "params": {"item_id": "1fd17ad3"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### item.flush
Flush all read items.
- **Arguments:** Nothing
- **Return on success:** true
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.flush", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### item.mark_all_as_read
Mark all unread items as read.
- **Arguments:** Nothing
- **Return on success:** true
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.mark_all_as_read", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### item.set_list_status
Change the status of a list of item id.
- **Arguments:** status (read, unread or removed), items (list of item id: ["id-1", "id-2", ...])
- **Return on success:** true
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.set_list_status", "params": {"status": "unread", "items": ["1fd17ad3", "bcc94722"]}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : true
}
```
### item.get_all
Get all items (unread and read)
- **Arguments:** Nothing
- **Return on success:** List of items
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.get_all", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : [
{
"bookmark" : "0",
"content" : "<p>Le comportement de molécules biologiques importantes est probablement différent dans un milieu ...</p>",
"feed_id" : "6",
"feed_title" : "Les dernières actualités de Futura-Sciences",
"id" : "947c27f1",
"site_url" : "http://www.futura-sciences.com",
"status" : "read",
"title" : "Des bulles de graphène piègent des moélcules sous le microscope",
"updated" : "1392467820",
"url" : "http://www.futura-sciences.com/magazines/matiere/infos/actu/d/physique-bulles-graphene-piegent-moelcules-sous-microscope-52264/#xtor=RSS-8"
},
...
]
}
```
### item.get_all_status
Get all items status (unread and read)
- **Arguments:** Nothing
- **Return on success:** List of items id and the status
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.get_all_status", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : {
"02043706" : "unread",
"03b2f912" : "read",
"087619e5" : "unread",
"0a05d7f2" : "read",
"0ab36a48" : "read",
"0d55fd54" : "read",
"0f64bd6d" : "read",
"0fff2adc" : "unread",
"10fc26ac" : "unread",
....
}
}
```
### item.get_all_since
Get all items since a date (unread and read)
- **Arguments:** Unix timestamp
- **Return on success:** List of items
- **Return on failure:** false
Request:
```json
curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.get_all_since", "params": {"timestamp": 1392467820}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php
```
Response:
```json
{ "id" : 1,
"jsonrpc" : "2.0",
"result" : [
{
"bookmark" : "0",
"content" : "<p>...</p>",
"feed_id" : "6",
"feed_title" : "Les dernières actualités de Futura-Sciences",
"id" : "dccc2a20",
"site_url" : "http://www.futura-sciences.com",
"status" : "read",
"title" : "Curiosity a franchi avec succès la dune de Dingo Gap",
"updated" : "1392475200",
"url" : "http://www.futura-sciences.com/magazines/espace/infos/actu/d/astronautique-curiosity-franchi-succes-dune-dingo-gap-52289/#xtor=RSS-8"
},
{
"bookmark" : "0",
"content" : "<p>...</p>",
"feed_id" : "6",
"feed_title" : "Les dernières actualités de Futura-Sciences",
"id" : "947c27f1",
"site_url" : "http://www.futura-sciences.com",
"status" : "read",
"title" : "Des bulles de graphène piègent des moélcules sous le microscope",
"updated" : "1392467820",
"url" : "http://www.futura-sciences.com/magazines/matiere/infos/actu/d/physique-bulles-graphene-piegent-moelcules-sous-microscope-52264/#xtor=RSS-8"
},
...
]
}
```
Reference in New Issue Copy Permalink