aboutsummaryrefslogtreecommitdiffhomepage
path: root/docs/fr/developer/api.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/fr/developer/api.rst')
-rw-r--r--docs/fr/developer/api.rst235
1 files changed, 235 insertions, 0 deletions
diff --git a/docs/fr/developer/api.rst b/docs/fr/developer/api.rst
new file mode 100644
index 00000000..9c8e25a9
--- /dev/null
+++ b/docs/fr/developer/api.rst
@@ -0,0 +1,235 @@
1Documentation de l'API
2======================
3
4Grâce à cette documentation, nous allons voir comment interagir avec l'API de wallabag.
5
6Pré-requis
7----------
8
9* wallabag fraichement installé et disponible à http://localhost:8000
10* ``httpie`` installé sur votre ordinateur (`voir le site du projet <https://github.com/jkbrzt/httpie>`__). Vous pouvez également adapter les commandes en utilisant curl ou wget.
11* toutes les méthodes de l'API documentées ici http://localhost:8000/api/doc
12
13Créer un nouveau client d'API
14-----------------------------
15
16Depuis votre wallabag, vous pouvez créer un nouveau client d'API à cette URL http://localhost:8000/developer/client/create.
17
18Vous devez renseigner l'URL de redirection de votre application et créer votre client. Si votre application est une application desktop, renseignez l'URL que vous souhaitez.
19
20Vous obtiendrez les informations suivantes :
21
22::
23
24 Client ID:
25
26 1_3o53gl30vhgk0c8ks4cocww08o84448osgo40wgw4gwkoo8skc
27
28 Client secret:
29
30 636ocbqo978ckw0gsw4gcwwocg8044sco0w8w84cws48ggogs4
31
32
33Créer un jeton
34--------------
35
36Pour chaque appel d'API, vous aurez besoin d'un jeton. Créons-le avec la commande suivante (remplacez ``client_id``, ``client_secret``, ``username`` and ``password`` par leur valeur):
37
38::
39
40 http POST http://localhost:8000/oauth/v2/token \
41 grant_type=password \
42 client_id=1_3o53gl30vhgk0c8ks4cocww08o84448osgo40wgw4gwkoo8skc \
43 client_secret=636ocbqo978ckw0gsw4gcwwocg8044sco0w8w84cws48ggogs4 \
44 username=wallabag \
45 password=wallabag
46
47Vous obtiendrez :
48
49::
50
51 HTTP/1.1 200 OK
52 Cache-Control: no-store, private
53 Connection: close
54 Content-Type: application/json
55 Date: Tue, 05 Apr 2016 08:44:33 GMT
56 Host: localhost:8000
57 Pragma: no-cache
58 X-Debug-Token: 19c8e0
59 X-Debug-Token-Link: /_profiler/19c8e0
60 X-Powered-By: PHP/7.0.4
61
62 {
63 "access_token": "ZGJmNTA2MDdmYTdmNWFiZjcxOWY3MWYyYzkyZDdlNWIzOTU4NWY3NTU1MDFjOTdhMTk2MGI3YjY1ZmI2NzM5MA",
64 "expires_in": 3600,
65 "refresh_token": "OTNlZGE5OTJjNWQwYzc2NDI5ZGE5MDg3ZTNjNmNkYTY0ZWZhZDVhNDBkZTc1ZTNiMmQ0MjQ0OThlNTFjNTQyMQ",
66 "scope": null,
67 "token_type": "bearer"
68 }
69
70Nous allons utiliser la valeur de ``access_token`` dans nos prochains appels.
71
72Récupérer les articles existants
73--------------------------------
74
75Documentation pour cette méthode : http://localhost:8000/api/doc#get--api-entries.{_format}
76
77Comme nous venons tout juste d'installer wallabag, nous n'aurons aucun résultat avec cette commande :
78
79::
80
81 http GET http://localhost:8000/api/entries.json \
82 "Authorization:Bearer ZGJmNTA2MDdmYTdmNWFiZjcxOWY3MWYyYzkyZDdlNWIzOTU4NWY3NTU1MDFjOTdhMTk2MGI3YjY1ZmI2NzM5MA"
83
84retournera :
85
86::
87
88 HTTP/1.1 200 OK
89 0: application/json
90 Cache-Control: no-cache
91 Connection: close
92 Content-Type: application/json
93 Date: Tue, 05 Apr 2016 08:51:32 GMT
94 Host: localhost:8000
95 Set-Cookie: PHPSESSID=nrogm748md610ovhu6j70c3q63; path=/; HttpOnly
96 X-Debug-Token: 4fbbc4
97 X-Debug-Token-Link: /_profiler/4fbbc4
98 X-Powered-By: PHP/7.0.4
99
100 {
101 "_embedded": {
102 "items": []
103 },
104 "_links": {
105 "first": {
106 "href": "http://localhost:8000/api/entries?page=1&perPage=30"
107 },
108 "last": {
109 "href": "http://localhost:8000/api/entries?page=1&perPage=30"
110 },
111 "self": {
112 "href": "http://localhost:8000/api/entries?page=1&perPage=30"
113 }
114 },
115 "limit": 30,
116 "page": 1,
117 "pages": 1,
118 "total": 0
119 }
120
121Le tableau ``items`` est vide.
122
123Créer votre premier article
124---------------------------
125
126Documentation pour cette méthode : http://localhost:8000/api/doc#post--api-entries.{_format}
127
128::
129
130 http POST http://localhost:8000/api/entries.json \
131 "Authorization:Bearer ZGJmNTA2MDdmYTdmNWFiZjcxOWY3MWYyYzkyZDdlNWIzOTU4NWY3NTU1MDFjOTdhMTk2MGI3YjY1ZmI2NzM5MA" \
132 url="http://www.numerama.com/tech/160115-le-pocket-libre-wallabag-fait-le-plein-de-fonctionnalites.html"
133
134retournera :
135
136::
137
138 HTTP/1.1 200 OK
139 0: application/json
140 Cache-Control: no-cache
141 Connection: close
142 Content-Type: application/json
143 Date: Tue, 05 Apr 2016 09:07:54 GMT
144 Host: localhost:8000
145 Set-Cookie: PHPSESSID=bjie40ck72kp2pst3i71gf43a4; path=/; HttpOnly
146 X-Debug-Token: e01c51
147 X-Debug-Token-Link: /_profiler/e01c51
148 X-Powered-By: PHP/7.0.4
149
150 {
151 "_links": {
152 "self": {
153 "href": "/api/entries/1"
154 }
155 },
156 "content": "<p class=\"chapo\">Fonctionnant sur le même principe que Pocket, Instapaper ou Readability, le logiciel Wallabag permet de mémoriser des articles pour les lire plus tard. Sa nouvelle version apporte une multitude de nouvelles fonctionnalités.</p><p>Si vous utilisez Firefox comme navigateur web, vous avez peut-être constaté l’arrivée d’<a href=\"http://www.numerama.com/magazine/33292-update-firefox.html\">une fonctionnalité intitulée Pocket</a>. Disponible autrefois sous la forme d’un module complémentaire, et sous un autre nom (Read it Later), elle est depuis le mois de juin 2015 directement incluse au sein de Firefox.</p>\n<p>Concrètement, Pocket sert à garder en mémoire des contenus que vous croisez au fil de la navigation, comme des articles de presse ou des vidéos, afin de pouvoir les consulter plus tard. Pocket fonctionne un peu comme un système de favoris, mais en bien plus élaboré grâce à ses options supplémentaires.</p>\n<p>Mais <a href=\"https://en.wikipedia.org/wiki/Pocket_%28application%29#Firefox_integration\" target=\"_blank\">Pocket fait polémique</a>, car il s’agit d’un projet propriétaire qui est intégré dans un logiciel libre. C’est pour cette raison que des utilisateurs ont choisi de se tourner vers d’autres solutions, comme <strong>Wallabag</strong>, qui est l’équivalent libre de Pocket et d’autres systèmes du même genre, comme Instapaper et Readability.</p>\n<p>Et justement, Wallabag évolue. C’est ce dimanche que la <a href=\"https://www.wallabag.org/blog/2016/04/03/wallabag-v2\" target=\"_blank\">version 2.0.0 du logiciel</a> a été publiée par l’équipe en  charge de son développement et celle-ci contient de nombreux changements par rapport aux moutures précédentes (la <a href=\"http://doc.wallabag.org/fr/v2/\" target=\"_blank\">documentation est traduite</a> en français), lui permettant d’apparaître comme une alternative à Pocket, Instapaper et Readability.</p>\n<p><img class=\"aligncenter size-medium wp-image-160439\" src=\"http://www.numerama.com/content/uploads/2016/04/homepage-680x347.png\" alt=\"homepage\" width=\"680\" height=\"347\" srcset=\"//www.numerama.com/content/uploads/2016/04/homepage-680x347.png 680w, //www.numerama.com/content/uploads/2016/04/homepage-1024x523.png 1024w, //www.numerama.com/content/uploads/2016/04/homepage-270x138.png 270w, //www.numerama.com/content/uploads/2016/04/homepage.png 1286w\" sizes=\"(max-width: 680px) 100vw, 680px\"/></p>\n<p>Parmi les principaux changements que l’on peut retenir avec cette nouvelle version, notons la possibilité d’écrire des annotations dans les articles mémorisés, de filtrer les contenus selon divers critères (temps de lecture, nom de domaine, date de création, statut…), d’assigner des mots-clés aux entrées, de modifier le titre des articles, le support des flux RSS ou encore le support de plusieurs langues dont le français.</p>\n<p>D’autres options sont également à signaler, comme l’aperçu d’un article mémorisé (si l’option est disponible), un guide de démarrage rapide pour les débutants, un outil d’export dans divers formats (PDF, JSON, EPUB, MOBI, XML, CSV et TXT) et, surtout, la possibilité de migrer vers Wallabag depuis Pocket, afin de convaincre les usagers de se lancer.</p>\n \n \n <footer class=\"clearfix\" readability=\"1\"><p class=\"source\">\n Crédit photo de la une : <a href=\"https://www.flickr.com/photos/bookgrl/2388310523/\">Laura Taylor</a>\n </p>\n \n <p><a href=\"http://www.numerama.com/tech/160115-le-pocket-libre-wallabag-fait-le-plein-de-fonctionnalites.html?&amp;show_reader_reports\" target=\"_blank\" rel=\"nofollow\">Signaler une erreur dans le texte</a></p>\n \n</footer> <section class=\"related-article\"><header><h3>Articles liés</h3>\n </header><article class=\"post-grid format-article\"><a class=\"floatleft\" href=\"http://www.numerama.com/magazine/34444-firefox-prepare-l-enterrement-des-vieux-plugins.html\" title=\"Firefox prépare l'enterrement des vieux plugins\">\n <div class=\"cover-preview cover-tech\">\n <p>Lire</p>\n \n \n \n <img class=\"cover-preview_img\" src=\"http://c2.lestechnophiles.com/www.numerama.com/content/uploads/2015/10/cimetierecolleville.jpg?resize=200,135\" srcset=\"&#10; //c2.lestechnophiles.com/www.numerama.com/content/uploads/2015/10/cimetierecolleville.jpg?resize=200,135 200w,&#10; //c2.lestechnophiles.com/www.numerama.com/content/uploads/2015/10/cimetierecolleville.jpg?resize=100,67 100w,&#10; \" sizes=\"(min-width: 1001px) 200px, (max-width: 1000px) 100px\" alt=\"Firefox prépare l'enterrement des vieux plugins\"/></div>\n <h4> Firefox prépare l'enterrement des vieux plugins </h4>\n </a>\n <footer class=\"span12\">\n </footer></article><article class=\"post-grid format-article\"><a class=\"floatleft\" href=\"http://www.numerama.com/tech/131636-activer-navigation-privee-navigateur-web.html\" title=\"Comment activer la navigation privée sur son navigateur web\">\n <div class=\"cover-preview cover-tech\">\n <p>Lire</p>\n \n \n \n <img class=\"cover-preview_img\" src=\"http://c1.lestechnophiles.com/www.numerama.com/content/uploads/2015/11/Incognito.jpg?resize=200,135\" srcset=\"&#10; //c1.lestechnophiles.com/www.numerama.com/content/uploads/2015/11/Incognito.jpg?resize=200,135 200w,&#10; //c1.lestechnophiles.com/www.numerama.com/content/uploads/2015/11/Incognito.jpg?resize=100,67 100w,&#10; \" sizes=\"(min-width: 1001px) 200px, (max-width: 1000px) 100px\" alt=\"Comment activer la navigation privée sur son navigateur web\"/></div>\n <h4> Comment activer la navigation privée sur son navigateur web </h4>\n </a>\n <footer class=\"span12\">\n </footer></article><article class=\"post-grid format-article\"><a class=\"floatleft\" href=\"http://www.numerama.com/tech/144028-firefox-se-mettra-a-jour-regulierement.html\" title=\"Firefox se mettra à jour un peu moins régulièrement\">\n <div class=\"cover-preview cover-tech\">\n <p>Lire</p>\n \n \n \n <img class=\"cover-preview_img\" src=\"http://c0.lestechnophiles.com/www.numerama.com/content/uploads/2016/02/firefox-mobile.jpg?resize=200,135\" srcset=\"&#10; //c0.lestechnophiles.com/www.numerama.com/content/uploads/2016/02/firefox-mobile.jpg?resize=200,135 200w,&#10; //c0.lestechnophiles.com/www.numerama.com/content/uploads/2016/02/firefox-mobile.jpg?resize=100,67 100w,&#10; \" sizes=\"(min-width: 1001px) 200px, (max-width: 1000px) 100px\" alt=\"Firefox se mettra à jour un peu moins régulièrement\"/></div>\n <h4> Firefox se mettra à jour un peu moins régulièrement </h4>\n </a>\n <footer class=\"span12\">\n </footer></article>\n</section>\n",
157 "created_at": "2016-04-05T09:07:54+0000",
158 "domain_name": "www.numerama.com",
159 "id": 1,
160 "is_archived": 0,
161 "is_starred": 0,
162 "language": "fr-FR",
163 "mimetype": "text/html",
164 "preview_picture": "http://www.numerama.com/content/uploads/2016/04/post-it.jpg",
165 "reading_time": 2,
166 "tags": [],
167 "title": "Le Pocket libre Wallabag fait le plein de fonctionnalités - Tech - Numerama",
168 "updated_at": "2016-04-05T09:07:54+0000",
169 "url": "http://www.numerama.com/tech/160115-le-pocket-libre-wallabag-fait-le-plein-de-fonctionnalites.html",
170 "user_email": "",
171 "user_id": 1,
172 "user_name": "wallabag"
173 }
174
175Maintenant, si vous exécutez la précédente commande (voir **Récupérer les articles existants**), vous obtiendrez quelque chose.
176
177Supprimer un article
178--------------------
179
180Documentation pour cette méthode : http://localhost:8000/api/doc#delete--api-entries-{entry}.{_format}
181
182::
183
184 http DELETE http://localhost:8000/api/entries/1.json \
185 "Authorization:Bearer ZGJmNTA2MDdmYTdmNWFiZjcxOWY3MWYyYzkyZDdlNWIzOTU4NWY3NTU1MDFjOTdhMTk2MGI3YjY1ZmI2NzM5MA"
186
187retournera :
188
189::
190
191 HTTP/1.1 200 OK
192 0: application/json
193 Cache-Control: no-cache
194 Connection: close
195 Content-Type: application/json
196 Date: Tue, 05 Apr 2016 09:19:07 GMT
197 Host: localhost:8000
198 Set-Cookie: PHPSESSID=jopgnfvmuc9a62b27sqm6iulr6; path=/; HttpOnly
199 X-Debug-Token: 887cef
200 X-Debug-Token-Link: /_profiler/887cef
201 X-Powered-By: PHP/7.0.4
202
203 {
204 "_links": {
205 "self": {
206 "href": "/api/entries/"
207 }
208 },
209 "annotations": [],
210 "content": "<p class=\"chapo\">Fonctionnant sur le même principe que Pocket, Instapaper ou Readability, le logiciel Wallabag permet de mémoriser des articles pour les lire plus tard. Sa nouvelle version apporte une multitude de nouvelles fonctionnalités.</p><p>Si vous utilisez Firefox comme navigateur web, vous avez peut-être constaté l’arrivée d’<a href=\"http://www.numerama.com/magazine/33292-update-firefox.html\">une fonctionnalité intitulée Pocket</a>. Disponible autrefois sous la forme d’un module complémentaire, et sous un autre nom (Read it Later), elle est depuis le mois de juin 2015 directement incluse au sein de Firefox.</p>\n<p>Concrètement, Pocket sert à garder en mémoire des contenus que vous croisez au fil de la navigation, comme des articles de presse ou des vidéos, afin de pouvoir les consulter plus tard. Pocket fonctionne un peu comme un système de favoris, mais en bien plus élaboré grâce à ses options supplémentaires.</p>\n<p>Mais <a href=\"https://en.wikipedia.org/wiki/Pocket_%28application%29#Firefox_integration\" target=\"_blank\">Pocket fait polémique</a>, car il s’agit d’un projet propriétaire qui est intégré dans un logiciel libre. C’est pour cette raison que des utilisateurs ont choisi de se tourner vers d’autres solutions, comme <strong>Wallabag</strong>, qui est l’équivalent libre de Pocket et d’autres systèmes du même genre, comme Instapaper et Readability.</p>\n<p>Et justement, Wallabag évolue. C’est ce dimanche que la <a href=\"https://www.wallabag.org/blog/2016/04/03/wallabag-v2\" target=\"_blank\">version 2.0.0 du logiciel</a> a été publiée par l’équipe en  charge de son développement et celle-ci contient de nombreux changements par rapport aux moutures précédentes (la <a href=\"http://doc.wallabag.org/fr/v2/\" target=\"_blank\">documentation est traduite</a> en français), lui permettant d’apparaître comme une alternative à Pocket, Instapaper et Readability.</p>\n<p><img class=\"aligncenter size-medium wp-image-160439\" src=\"http://www.numerama.com/content/uploads/2016/04/homepage-680x347.png\" alt=\"homepage\" width=\"680\" height=\"347\" srcset=\"//www.numerama.com/content/uploads/2016/04/homepage-680x347.png 680w, //www.numerama.com/content/uploads/2016/04/homepage-1024x523.png 1024w, //www.numerama.com/content/uploads/2016/04/homepage-270x138.png 270w, //www.numerama.com/content/uploads/2016/04/homepage.png 1286w\" sizes=\"(max-width: 680px) 100vw, 680px\"/></p>\n<p>Parmi les principaux changements que l’on peut retenir avec cette nouvelle version, notons la possibilité d’écrire des annotations dans les articles mémorisés, de filtrer les contenus selon divers critères (temps de lecture, nom de domaine, date de création, statut…), d’assigner des mots-clés aux entrées, de modifier le titre des articles, le support des flux RSS ou encore le support de plusieurs langues dont le français.</p>\n<p>D’autres options sont également à signaler, comme l’aperçu d’un article mémorisé (si l’option est disponible), un guide de démarrage rapide pour les débutants, un outil d’export dans divers formats (PDF, JSON, EPUB, MOBI, XML, CSV et TXT) et, surtout, la possibilité de migrer vers Wallabag depuis Pocket, afin de convaincre les usagers de se lancer.</p>\n \n \n <footer class=\"clearfix\" readability=\"1\"><p class=\"source\">\n Crédit photo de la une : <a href=\"https://www.flickr.com/photos/bookgrl/2388310523/\">Laura Taylor</a>\n </p>\n \n <p><a href=\"http://www.numerama.com/tech/160115-le-pocket-libre-wallabag-fait-le-plein-de-fonctionnalites.html?&amp;show_reader_reports\" target=\"_blank\" rel=\"nofollow\">Signaler une erreur dans le texte</a></p>\n \n</footer> <section class=\"related-article\"><header><h3>Articles liés</h3>\n </header><article class=\"post-grid format-article\"><a class=\"floatleft\" href=\"http://www.numerama.com/magazine/34444-firefox-prepare-l-enterrement-des-vieux-plugins.html\" title=\"Firefox prépare l'enterrement des vieux plugins\">\n <div class=\"cover-preview cover-tech\">\n <p>Lire</p>\n \n \n \n <img class=\"cover-preview_img\" src=\"http://c2.lestechnophiles.com/www.numerama.com/content/uploads/2015/10/cimetierecolleville.jpg?resize=200,135\" srcset=\"&#10; //c2.lestechnophiles.com/www.numerama.com/content/uploads/2015/10/cimetierecolleville.jpg?resize=200,135 200w,&#10; //c2.lestechnophiles.com/www.numerama.com/content/uploads/2015/10/cimetierecolleville.jpg?resize=100,67 100w,&#10; \" sizes=\"(min-width: 1001px) 200px, (max-width: 1000px) 100px\" alt=\"Firefox prépare l'enterrement des vieux plugins\"/></div>\n <h4> Firefox prépare l'enterrement des vieux plugins </h4>\n </a>\n <footer class=\"span12\">\n </footer></article><article class=\"post-grid format-article\"><a class=\"floatleft\" href=\"http://www.numerama.com/tech/131636-activer-navigation-privee-navigateur-web.html\" title=\"Comment activer la navigation privée sur son navigateur web\">\n <div class=\"cover-preview cover-tech\">\n <p>Lire</p>\n \n \n \n <img class=\"cover-preview_img\" src=\"http://c1.lestechnophiles.com/www.numerama.com/content/uploads/2015/11/Incognito.jpg?resize=200,135\" srcset=\"&#10; //c1.lestechnophiles.com/www.numerama.com/content/uploads/2015/11/Incognito.jpg?resize=200,135 200w,&#10; //c1.lestechnophiles.com/www.numerama.com/content/uploads/2015/11/Incognito.jpg?resize=100,67 100w,&#10; \" sizes=\"(min-width: 1001px) 200px, (max-width: 1000px) 100px\" alt=\"Comment activer la navigation privée sur son navigateur web\"/></div>\n <h4> Comment activer la navigation privée sur son navigateur web </h4>\n </a>\n <footer class=\"span12\">\n </footer></article><article class=\"post-grid format-article\"><a class=\"floatleft\" href=\"http://www.numerama.com/tech/144028-firefox-se-mettra-a-jour-regulierement.html\" title=\"Firefox se mettra à jour un peu moins régulièrement\">\n <div class=\"cover-preview cover-tech\">\n <p>Lire</p>\n \n \n \n <img class=\"cover-preview_img\" src=\"http://c0.lestechnophiles.com/www.numerama.com/content/uploads/2016/02/firefox-mobile.jpg?resize=200,135\" srcset=\"&#10; //c0.lestechnophiles.com/www.numerama.com/content/uploads/2016/02/firefox-mobile.jpg?resize=200,135 200w,&#10; //c0.lestechnophiles.com/www.numerama.com/content/uploads/2016/02/firefox-mobile.jpg?resize=100,67 100w,&#10; \" sizes=\"(min-width: 1001px) 200px, (max-width: 1000px) 100px\" alt=\"Firefox se mettra à jour un peu moins régulièrement\"/></div>\n <h4> Firefox se mettra à jour un peu moins régulièrement </h4>\n </a>\n <footer class=\"span12\">\n </footer></article>\n</section>\n",
211 "created_at": "2016-04-05T09:07:54+0000",
212 "domain_name": "www.numerama.com",
213 "is_archived": 0,
214 "is_starred": 0,
215 "language": "fr-FR",
216 "mimetype": "text/html",
217 "preview_picture": "http://www.numerama.com/content/uploads/2016/04/post-it.jpg",
218 "reading_time": 2,
219 "tags": [],
220 "title": "Le Pocket libre Wallabag fait le plein de fonctionnalités - Tech - Numerama",
221 "updated_at": "2016-04-05T09:07:54+0000",
222 "url": "http://www.numerama.com/tech/160115-le-pocket-libre-wallabag-fait-le-plein-de-fonctionnalites.html",
223 "user_email": "",
224 "user_id": 1,
225 "user_name": "wallabag"
226 }
227
228Et si vous voulez voir la liste des articles existants (voir **Récupérer les articles existants**), le tableau sera vide.
229
230Autres méthodes
231---------------
232
233Nous n'écrirons pas d'exemples pour toutes les méthodes de l'API.
234
235Jetez un œil à la liste complète ici http://localhost:8000/api/doc pour connaitre chaque méthode.