Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
A bit of API documentation (#1914)
  • Loading branch information
Alkarex committed Jun 3, 2018
1 parent ccc62b0 commit 4b9f071
Show file tree
Hide file tree
Showing 7 changed files with 81 additions and 8 deletions.
2 changes: 1 addition & 1 deletion CHANGELOG.md
Expand Up @@ -25,7 +25,7 @@
* Fix Docker bug affecting Apache `CustomLog` (unwanted local copy of access logs), `ErrorLog`, `Listen` (IPv6 bug) [#1873](https://github.com/FreshRSS/FreshRSS/pull/1873)
* Fix muted feeds that were not actually muted [#1844](https://github.com/FreshRSS/FreshRSS/issues/1844)
* Fix null exception in shares, showing only the first article [#1824](https://github.com/FreshRSS/FreshRSS/issues/1824)
* Fix error during import[#1890](https://github.com/FreshRSS/FreshRSS/issues/1890)
* Fix error during import [#1890](https://github.com/FreshRSS/FreshRSS/issues/1890)
* Fix additional automatic sequence bug with PostgreSQL [#1907](https://github.com/FreshRSS/FreshRSS/pull/1907)
* Fix errors in case of empty/wrong username when updating user settings [#1857](https://github.com/FreshRSS/FreshRSS/pull/1857)
* Fixes in subscription menu [#1858](https://github.com/FreshRSS/FreshRSS/pull/1858)
Expand Down
6 changes: 3 additions & 3 deletions README.fr.md
Expand Up @@ -186,10 +186,10 @@ Voir notre [documentation sur l’API Fever](https://freshrss.github.io/FreshRSS
Tout client supportant une API de type Fever ; Sélection :

* iOS
* [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303)
* [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153)
* [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303) (Propriétaire)
* [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153) (Propriétaire)
* MacOS
* [Readkit](https://itunes.apple.com/app/readkit/id588726889)
* [Readkit](https://itunes.apple.com/app/readkit/id588726889) (Propriétaire)


# Bibliothèques incluses
Expand Down
6 changes: 3 additions & 3 deletions README.md
Expand Up @@ -186,10 +186,10 @@ See our [Fever API documentation](https://freshrss.github.io/FreshRSS/en/users/0
Supported clients are:

* iOS
* [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303)
* [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153)
* [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303) (Closed source)
* [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153) (Closed source)
* MacOS
* [Readkit](https://itunes.apple.com/app/readkit/id588726889)
* [Readkit](https://itunes.apple.com/app/readkit/id588726889) (Closed source)


# Included libraries
Expand Down
3 changes: 3 additions & 0 deletions docs/en/users/06_Fever_API.md
@@ -1,5 +1,8 @@
# 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 existing supporting Fever APIs but they seem to understand the Fever API a bit differently.
Expand Down
34 changes: 34 additions & 0 deletions docs/en/users/06_Mobile_access.md
Expand Up @@ -7,6 +7,9 @@ This page assumes you have completed the [server setup](../admins/02_Installatio
* Every user must define an API password.
* The reason for an API-specific password is that it may be used in less safe situations than the main password, and does not grant access to as many things.

The rest of this page is about the Google Reader compatible API.
See the [page about the Fever compatible API](06_Fever_API.md) for another possibility.


# Testing

Expand Down Expand Up @@ -50,3 +53,34 @@ This page assumes you have completed the [server setup](../admins/02_Installatio
* [EasyRSS](https://github.com/Alkarex/EasyRSS) (Open source, [F-Droid](https://f-droid.org/packages/org.freshrss.easyrss/))
* Linux
* [FeedReader 2.0+](https://jangernert.github.io/FeedReader/) (Open source)


# Google Reader compatible API

Examples of basic queries:

```sh
# Initial login, using API password (Email and Passwd can be given either as GET, or POST - better)
curl 'https://freshrss.example.net/api/greader.php/accounts/ClientLogin?Email=alice&Passwd=Abcdef123456'
SID=alice/8e6845e089457af25303abc6f53356eb60bdb5f8
Auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8

# Examples of read-only requests
curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list?output=json'

curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count?output=json'

curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list?output=json'

# Retrieve a token for requests making modifications
curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/token'
8e6845e089457af25303abc6f53356eb60bdb5f8ZZZZZZZZZZZZZZZZZ

# Get articles, piped to jq for easier JSON reading
curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/reading-list' | jq .
```
2 changes: 2 additions & 0 deletions docs/fr/users/06_Fever_API.md
@@ -1,5 +1,7 @@
# FreshRSS - API compatible Fever

Voir la page [sur notre API compatible Google Reader](06_Mobile_access.md) pour une autre possibilité
et des généralités sur l’accès par API.

## Compatibilité

Expand Down
36 changes: 35 additions & 1 deletion docs/fr/users/06_Mobile_access.md
Expand Up @@ -7,6 +7,9 @@ Cette page suppose que vous avez fini [l’installation du serveur](01_Installat
* Chaque utilisateur doit choisir son mot de passe API.
* La raison d’être d’un mot de passe API différent du mot de passe principal est que le mot de passe API est potentiellement utilisé de manière moins sûre, mais il permet aussi moins de choses.

Le reste de cette page concerne l’API compatible Google Reader.
Voir la [page sur l’API compatible Fever](06_Fever_API.md) pour une autre possibilité.


# Tester

Expand All @@ -17,7 +20,7 @@ Cette page suppose que vous avez fini [l’installation du serveur](01_Installat
* Si vous obtenez un autre message d’erreur, passer à l’étape 5.


# Débogger la configuration du serveur
# Déboguer la configuration du serveur

5. Cliquer sur le second lien “Check partial server configuration (without `%2F` support)”:
* Si vous obtenez `PASS`, alors le problème est bien que votre serveur n’accepte pas les slashs `/` qui sont encodés `%2F`.
Expand Down Expand Up @@ -48,3 +51,34 @@ Tout client supportant une API de type Google Reader. Sélection :
* [EasyRSS](https://github.com/Alkarex/EasyRSS) (Libre, F-Droid)
* Linux
* [FeedReader 2.0+](https://jangernert.github.io/FeedReader/) (Libre)


# API compatible Google Reader

Exemples de requêtes simples:

```sh
# Authentification utilisant le mot de passe API (Email et Passwd peuvent être passés en GET, ou POST - mieux)
curl 'https://freshrss.example.net/api/greader.php/accounts/ClientLogin?Email=alice&Passwd=Abcdef123456'
SID=alice/8e6845e089457af25303abc6f53356eb60bdb5f8
Auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8

# Exemples de requêtes en lecture
curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list?output=json'

curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count?output=json'

curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list?output=json'

# Demande de jeton pour faire de requêtes de modification
curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/token'
8e6845e089457af25303abc6f53356eb60bdb5f8ZZZZZZZZZZZZZZZZZ

# Récupère les articles, envoyés à jq pour une lecture JSON plus facile
curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/reading-list' | jq .
```

0 comments on commit 4b9f071

Please sign in to comment.